From cb39df273de782be1145dc5184bfd47d823531d5 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Sat, 22 Jun 2024 09:10:58 +0100 Subject: Remove deprecated `led_set_user` (#23979) --- docs/features/led_indicators.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'docs/features') 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: -- cgit v1.2.3 From bc0c69570b8a8b1d9a754a280053e49a825b24d7 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 3 Jul 2024 17:18:27 +1000 Subject: Rename encoder pins defines (#24003) --- docs/features/encoders.md | 28 +++++++++---------- docs/features/split_keyboard.md | 4 +-- drivers/encoder/encoder_quadrature.c | 18 ++++++------- .../dailycraft/wings42/rev2/keymaps/via/config.h | 4 +-- keyboards/handwired/sick68/keymaps/via/config.h | 4 +-- .../kapcave/gskt00/keymaps/default-poly/config.h | 4 +-- keyboards/pica40/rev2/rev2.c | 4 +-- keyboards/ploopyco/mouse/config.h | 4 +-- keyboards/ploopyco/ploopyco.c | 4 +-- keyboards/ploopyco/trackball/config.h | 4 +-- keyboards/ploopyco/trackball_mini/config.h | 4 +-- keyboards/ploopyco/trackball_thumb/config.h | 4 +-- keyboards/rgbkb/sol/keymaps/default/keymap.c | 2 +- keyboards/rgbkb/sol/rev2/config.h | 8 +++--- keyboards/terrazzo/readme.md | 4 +-- lib/python/qmk/cli/generate/config_h.py | 4 +-- lib/python/qmk/info.py | 4 +-- quantum/encoder.h | 31 ++++++++++++++-------- quantum/encoder/tests/config_mock.h | 4 +-- .../tests/config_mock_split_left_eq_right.h | 8 +++--- .../tests/config_mock_split_left_gt_right.h | 8 +++--- .../tests/config_mock_split_left_lt_right.h | 8 +++--- quantum/encoder/tests/config_mock_split_no_left.h | 8 +++--- quantum/encoder/tests/config_mock_split_no_right.h | 8 +++--- quantum/encoder/tests/config_mock_split_role.h | 8 +++--- 25 files changed, 100 insertions(+), 91 deletions(-) (limited to 'docs/features') diff --git a/docs/features/encoders.md b/docs/features/encoders.md index 3d1cac79af..eea70dafec 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 } ``` @@ -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/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. diff --git a/drivers/encoder/encoder_quadrature.c b/drivers/encoder/encoder_quadrature.c index cd589bf1e2..086f500391 100644 --- a/drivers/encoder/encoder_quadrature.c +++ b/drivers/encoder/encoder_quadrature.c @@ -22,7 +22,7 @@ #endif #undef ENCODER_DEFAULT_PIN_API_IMPL -#if defined(ENCODERS_PAD_A) && defined(ENCODERS_PAD_B) +#if defined(ENCODER_A_PINS) && defined(ENCODER_B_PINS) // Inform the quadrature driver that it needs to implement pin init/read functions # define ENCODER_DEFAULT_PIN_API_IMPL #endif @@ -34,8 +34,8 @@ __attribute__((weak)) uint8_t encoder_quadrature_read_pin(uint8_t index, bool pa #ifdef ENCODER_DEFAULT_PIN_API_IMPL -static pin_t encoders_pad_a[NUM_ENCODERS_MAX_PER_SIDE] = ENCODERS_PAD_A; -static pin_t encoders_pad_b[NUM_ENCODERS_MAX_PER_SIDE] = ENCODERS_PAD_B; +static pin_t encoders_pad_a[NUM_ENCODERS_MAX_PER_SIDE] = ENCODER_A_PINS; +static pin_t encoders_pad_b[NUM_ENCODERS_MAX_PER_SIDE] = ENCODER_B_PINS; __attribute__((weak)) void encoder_wait_pullup_charge(void) { wait_us(100); @@ -123,25 +123,25 @@ void encoder_driver_init(void) { // here, but it's the simplest solution. memset(encoder_state, 0, sizeof(encoder_state)); memset(encoder_pulses, 0, sizeof(encoder_pulses)); - const pin_t encoders_pad_a_left[] = ENCODERS_PAD_A; - const pin_t encoders_pad_b_left[] = ENCODERS_PAD_B; + const pin_t encoders_pad_a_left[] = ENCODER_A_PINS; + const pin_t encoders_pad_b_left[] = ENCODER_B_PINS; for (uint8_t i = 0; i < thisCount; i++) { encoders_pad_a[i] = encoders_pad_a_left[i]; encoders_pad_b[i] = encoders_pad_b_left[i]; } #endif -#if defined(SPLIT_KEYBOARD) && defined(ENCODERS_PAD_A_RIGHT) && defined(ENCODERS_PAD_B_RIGHT) +#if defined(SPLIT_KEYBOARD) && defined(ENCODER_A_PINS_RIGHT) && defined(ENCODER_B_PINS_RIGHT) // Re-initialise the pads if it's the right-hand side if (!isLeftHand) { - const pin_t encoders_pad_a_right[] = ENCODERS_PAD_A_RIGHT; - const pin_t encoders_pad_b_right[] = ENCODERS_PAD_B_RIGHT; + const pin_t encoders_pad_a_right[] = ENCODER_A_PINS_RIGHT; + const pin_t encoders_pad_b_right[] = ENCODER_B_PINS_RIGHT; for (uint8_t i = 0; i < thisCount; i++) { encoders_pad_a[i] = encoders_pad_a_right[i]; encoders_pad_b[i] = encoders_pad_b_right[i]; } } -#endif // defined(SPLIT_KEYBOARD) && defined(ENCODERS_PAD_A_RIGHT) && defined(ENCODERS_PAD_B_RIGHT) +#endif // defined(SPLIT_KEYBOARD) && defined(ENCODER_A_PINS_RIGHT) && defined(ENCODER_B_PINS_RIGHT) // Encoder resolutions is defined differently in config.h, so concatenate #if defined(SPLIT_KEYBOARD) && defined(ENCODER_RESOLUTIONS) diff --git a/keyboards/dailycraft/wings42/rev2/keymaps/via/config.h b/keyboards/dailycraft/wings42/rev2/keymaps/via/config.h index 3e0c8d146a..6a9ab04738 100644 --- a/keyboards/dailycraft/wings42/rev2/keymaps/via/config.h +++ b/keyboards/dailycraft/wings42/rev2/keymaps/via/config.h @@ -15,6 +15,6 @@ */ #pragma once -#define ENCODERS_PAD_A { B5, B6 } -#define ENCODERS_PAD_B { B4, B2 } +#define ENCODER_A_PINS { B5, B6 } +#define ENCODER_B_PINS { B4, B2 } #define ENCODER_RESOLUTION 4 diff --git a/keyboards/handwired/sick68/keymaps/via/config.h b/keyboards/handwired/sick68/keymaps/via/config.h index 4ce1e3e785..bf6fd3ea4f 100644 --- a/keyboards/handwired/sick68/keymaps/via/config.h +++ b/keyboards/handwired/sick68/keymaps/via/config.h @@ -15,6 +15,6 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . */ -#define ENCODERS_PAD_A { F0 } -#define ENCODERS_PAD_B { F1 } +#define ENCODER_A_PINS { F0 } +#define ENCODER_B_PINS { F1 } #define ENCODER_RESOLUTION 4 diff --git a/keyboards/kapcave/gskt00/keymaps/default-poly/config.h b/keyboards/kapcave/gskt00/keymaps/default-poly/config.h index 40a7c6ec47..9d03a669c8 100644 --- a/keyboards/kapcave/gskt00/keymaps/default-poly/config.h +++ b/keyboards/kapcave/gskt00/keymaps/default-poly/config.h @@ -16,8 +16,8 @@ along with this program. If not, see . */ #pragma once -#define ENCODERS_PAD_A { D5 } -#define ENCODERS_PAD_B { D3 } +#define ENCODER_A_PINS { D5 } +#define ENCODER_B_PINS { D3 } #define WS2812_DI_PIN D0 #define RGBLIGHT_EFFECT_BREATHING diff --git a/keyboards/pica40/rev2/rev2.c b/keyboards/pica40/rev2/rev2.c index 0ba9a53734..b5d79508fc 100644 --- a/keyboards/pica40/rev2/rev2.c +++ b/keyboards/pica40/rev2/rev2.c @@ -6,8 +6,8 @@ #ifdef ENCODER_ENABLE // code based on encoder.c -#define ENCODER_PIN_A (((pin_t[])ENCODERS_PAD_A)[0]) -#define ENCODER_PIN_B (((pin_t[])ENCODERS_PAD_B)[0]) +#define ENCODER_PIN_A (((pin_t[])ENCODER_A_PINS)[0]) +#define ENCODER_PIN_B (((pin_t[])ENCODER_B_PINS)[0]) // custom handler that returns encoder B pin status from slave side void encoder_sync_slave_handler(uint8_t in_buflen, const void *in_data, uint8_t out_buflen, void *out_data) { diff --git a/keyboards/ploopyco/mouse/config.h b/keyboards/ploopyco/mouse/config.h index 0375a8875a..0f8774dcd7 100644 --- a/keyboards/ploopyco/mouse/config.h +++ b/keyboards/ploopyco/mouse/config.h @@ -38,5 +38,5 @@ /* Custom encoder needs to specify just how many encoders we have */ #define NUM_ENCODERS 1 -#define ENCODERS_PAD_A { F0 } -#define ENCODERS_PAD_B { F4 } +#define ENCODER_A_PINS { F0 } +#define ENCODER_B_PINS { F4 } diff --git a/keyboards/ploopyco/ploopyco.c b/keyboards/ploopyco/ploopyco.c index e4726238f2..a6f76203d6 100644 --- a/keyboards/ploopyco/ploopyco.c +++ b/keyboards/ploopyco/ploopyco.c @@ -71,8 +71,8 @@ float scroll_accumulated_v = 0; #ifdef ENCODER_ENABLE uint16_t lastScroll = 0; // Previous confirmed wheel event uint16_t lastMidClick = 0; // Stops scrollwheel from being read if it was pressed -pin_t encoder_pins_a[1] = ENCODERS_PAD_A; -pin_t encoder_pins_b[1] = ENCODERS_PAD_B; +pin_t encoder_pins_a[1] = ENCODER_A_PINS; +pin_t encoder_pins_b[1] = ENCODER_B_PINS; bool debug_encoder = false; bool encoder_update_kb(uint8_t index, bool clockwise) { diff --git a/keyboards/ploopyco/trackball/config.h b/keyboards/ploopyco/trackball/config.h index 80457d062a..2aac27437a 100644 --- a/keyboards/ploopyco/trackball/config.h +++ b/keyboards/ploopyco/trackball/config.h @@ -38,5 +38,5 @@ /* Custom encoder needs to specify just how many encoders we have */ #define NUM_ENCODERS 1 -#define ENCODERS_PAD_A { F0 } -#define ENCODERS_PAD_B { F4 } +#define ENCODER_A_PINS { F0 } +#define ENCODER_B_PINS { F4 } diff --git a/keyboards/ploopyco/trackball_mini/config.h b/keyboards/ploopyco/trackball_mini/config.h index c5d2d5694e..2e0b570bba 100644 --- a/keyboards/ploopyco/trackball_mini/config.h +++ b/keyboards/ploopyco/trackball_mini/config.h @@ -38,5 +38,5 @@ /* Custom encoder needs to specify just how many encoders we have */ #define NUM_ENCODERS 1 -#define ENCODERS_PAD_A { F0 } -#define ENCODERS_PAD_B { F4 } +#define ENCODER_A_PINS { F0 } +#define ENCODER_B_PINS { F4 } diff --git a/keyboards/ploopyco/trackball_thumb/config.h b/keyboards/ploopyco/trackball_thumb/config.h index 631456d9d3..f03ffc7699 100644 --- a/keyboards/ploopyco/trackball_thumb/config.h +++ b/keyboards/ploopyco/trackball_thumb/config.h @@ -42,5 +42,5 @@ /* Custom encoder needs to specify just how many encoders we have */ #define NUM_ENCODERS 1 -#define ENCODERS_PAD_A { F4 } -#define ENCODERS_PAD_B { F0 } +#define ENCODER_A_PINS { F4 } +#define ENCODER_B_PINS { F0 } diff --git a/keyboards/rgbkb/sol/keymaps/default/keymap.c b/keyboards/rgbkb/sol/keymaps/default/keymap.c index 4a6511cbfc..8997e9a582 100644 --- a/keyboards/rgbkb/sol/keymaps/default/keymap.c +++ b/keyboards/rgbkb/sol/keymaps/default/keymap.c @@ -201,7 +201,7 @@ const rgb_matrix_f rgb_matrix_functions[6][2] = { #ifdef ENCODER_ENABLE -static pin_t encoders_pad_a[] = ENCODERS_PAD_A; +static pin_t encoders_pad_a[] = ENCODER_A_PINS; #define NUMBER_OF_ENCODERS ARRAY_SIZE(encoders_pad_a) const uint16_t PROGMEM encoders[][NUMBER_OF_ENCODERS * 2][2] = { diff --git a/keyboards/rgbkb/sol/rev2/config.h b/keyboards/rgbkb/sol/rev2/config.h index ab5150051a..5867c6dfe3 100644 --- a/keyboards/rgbkb/sol/rev2/config.h +++ b/keyboards/rgbkb/sol/rev2/config.h @@ -49,12 +49,12 @@ along with this program. If not, see . // Encoder support #ifndef EXTRA_ENCODERS_ENABLE -#define ENCODERS_PAD_A { D2 } -#define ENCODERS_PAD_B { D6 } +#define ENCODER_A_PINS { D2 } +#define ENCODER_B_PINS { D6 } #else #ifdef OLED_ENABLE #error Extra encoders cannot be enabled at the same time as the OLED Driver as they use the same pins. #endif -#define ENCODERS_PAD_A { D2, D1, B0 } -#define ENCODERS_PAD_B { D6, B1, D0 } +#define ENCODER_A_PINS { D2, D1, B0 } +#define ENCODER_B_PINS { D6, B1, D0 } #endif diff --git a/keyboards/terrazzo/readme.md b/keyboards/terrazzo/readme.md index e0f4f3457f..828819f7b4 100644 --- a/keyboards/terrazzo/readme.md +++ b/keyboards/terrazzo/readme.md @@ -82,8 +82,8 @@ Change pinouts, Pro Micro does not have the "F0" pin. Set encoder to just top or bottom position. ``` -#define ENCODERS_PAD_A { C6 } -#define ENCODERS_PAD_B { D4 } +#define ENCODER_A_PINS { C6 } +#define ENCODER_B_PINS { D4 } ``` ## Encoder Setup diff --git a/lib/python/qmk/cli/generate/config_h.py b/lib/python/qmk/cli/generate/config_h.py index fc681300a3..d613f7b92c 100755 --- a/lib/python/qmk/cli/generate/config_h.py +++ b/lib/python/qmk/cli/generate/config_h.py @@ -135,8 +135,8 @@ def generate_encoder_config(encoder_json, config_h_lines, postfix=''): b_pads.append(encoder["pin_b"]) resolutions.append(encoder.get("resolution", None)) - config_h_lines.append(generate_define(f'ENCODERS_PAD_A{postfix}', f'{{ {", ".join(a_pads)} }}')) - config_h_lines.append(generate_define(f'ENCODERS_PAD_B{postfix}', f'{{ {", ".join(b_pads)} }}')) + config_h_lines.append(generate_define(f'ENCODER_A_PINS{postfix}', f'{{ {", ".join(a_pads)} }}')) + config_h_lines.append(generate_define(f'ENCODER_B_PINS{postfix}', f'{{ {", ".join(b_pads)} }}')) if None in resolutions: cli.log.debug(f"Unable to generate ENCODER_RESOLUTION{postfix} configuration") diff --git a/lib/python/qmk/info.py b/lib/python/qmk/info.py index 091a11854c..5b3b249015 100644 --- a/lib/python/qmk/info.py +++ b/lib/python/qmk/info.py @@ -375,8 +375,8 @@ def _extract_audio(info_data, config_c): def _extract_encoders_values(config_c, postfix=''): """Common encoder extraction logic """ - a_pad = config_c.get(f'ENCODERS_PAD_A{postfix}', '').replace(' ', '')[1:-1] - b_pad = config_c.get(f'ENCODERS_PAD_B{postfix}', '').replace(' ', '')[1:-1] + a_pad = config_c.get(f'ENCODER_A_PINS{postfix}', '').replace(' ', '')[1:-1] + b_pad = config_c.get(f'ENCODER_B_PINS{postfix}', '').replace(' ', '')[1:-1] resolutions = config_c.get(f'ENCODER_RESOLUTIONS{postfix}', '').replace(' ', '')[1:-1] default_resolution = config_c.get('ENCODER_RESOLUTION', None) diff --git a/quantum/encoder.h b/quantum/encoder.h index 317a91f1da..1d2f1f46c7 100644 --- a/quantum/encoder.h +++ b/quantum/encoder.h @@ -22,6 +22,21 @@ #include "gpio.h" #include "util.h" +// ======== DEPRECATED DEFINES - DO NOT USE ======== +#ifdef ENCODERS_PAD_A +# define ENCODER_A_PINS ENCODERS_PAD_A +#endif +#ifdef ENCODERS_PAD_B +# define ENCODER_B_PINS ENCODERS_PAD_B +#endif +#ifdef ENCODERS_PAD_A_RIGHT +# define ENCODER_A_PINS_RIGHT ENCODERS_PAD_A_RIGHT +#endif +#ifdef ENCODERS_PAD_B_RIGHT +# define ENCODER_B_PINS_RIGHT ENCODERS_PAD_B_RIGHT +#endif +// ======== + #ifdef ENCODER_ENABLE __attribute__((weak)) bool should_process_encoder(void); @@ -36,16 +51,16 @@ bool encoder_update_user(uint8_t index, bool clockwise); # ifdef SPLIT_KEYBOARD -# if defined(ENCODERS_PAD_A_RIGHT) +# if defined(ENCODER_A_PINS_RIGHT) # ifndef NUM_ENCODERS_LEFT -# define NUM_ENCODERS_LEFT ARRAY_SIZE(((pin_t[])ENCODERS_PAD_A)) +# define NUM_ENCODERS_LEFT ARRAY_SIZE(((pin_t[])ENCODER_A_PINS)) # endif # ifndef NUM_ENCODERS_RIGHT -# define NUM_ENCODERS_RIGHT ARRAY_SIZE(((pin_t[])ENCODERS_PAD_A_RIGHT)) +# define NUM_ENCODERS_RIGHT ARRAY_SIZE(((pin_t[])ENCODER_A_PINS_RIGHT)) # endif # else # ifndef NUM_ENCODERS_LEFT -# define NUM_ENCODERS_LEFT ARRAY_SIZE(((pin_t[])ENCODERS_PAD_A)) +# define NUM_ENCODERS_LEFT ARRAY_SIZE(((pin_t[])ENCODER_A_PINS)) # endif # ifndef NUM_ENCODERS_RIGHT # define NUM_ENCODERS_RIGHT NUM_ENCODERS_LEFT @@ -58,19 +73,13 @@ bool encoder_update_user(uint8_t index, bool clockwise); # else // SPLIT_KEYBOARD # ifndef NUM_ENCODERS -# define NUM_ENCODERS ARRAY_SIZE(((pin_t[])ENCODERS_PAD_A)) +# define NUM_ENCODERS ARRAY_SIZE(((pin_t[])ENCODER_A_PINS)) # endif # define NUM_ENCODERS_LEFT NUM_ENCODERS # define NUM_ENCODERS_RIGHT 0 # endif // SPLIT_KEYBOARD -# ifndef NUM_ENCODERS -# define NUM_ENCODERS 0 -# define NUM_ENCODERS_LEFT 0 -# define NUM_ENCODERS_RIGHT 0 -# endif // NUM_ENCODERS - # define NUM_ENCODERS_MAX_PER_SIDE MAX(NUM_ENCODERS_LEFT, NUM_ENCODERS_RIGHT) # ifndef MAX_QUEUED_ENCODER_EVENTS diff --git a/quantum/encoder/tests/config_mock.h b/quantum/encoder/tests/config_mock.h index 9eb59ddc88..b5a1537d8a 100644 --- a/quantum/encoder/tests/config_mock.h +++ b/quantum/encoder/tests/config_mock.h @@ -7,9 +7,9 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ { 0 } -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ { 1 } #ifdef __cplusplus diff --git a/quantum/encoder/tests/config_mock_split_left_eq_right.h b/quantum/encoder/tests/config_mock_split_left_eq_right.h index ea795657ef..a4aa051ef1 100644 --- a/quantum/encoder/tests/config_mock_split_left_eq_right.h +++ b/quantum/encoder/tests/config_mock_split_left_eq_right.h @@ -7,13 +7,13 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ { 0, 2 } -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ { 1, 3 } -#define ENCODERS_PAD_A_RIGHT \ +#define ENCODER_A_PINS_RIGHT \ { 4, 6 } -#define ENCODERS_PAD_B_RIGHT \ +#define ENCODER_B_PINS_RIGHT \ { 5, 7 } #ifdef __cplusplus diff --git a/quantum/encoder/tests/config_mock_split_left_gt_right.h b/quantum/encoder/tests/config_mock_split_left_gt_right.h index abcfe03918..77190797ad 100644 --- a/quantum/encoder/tests/config_mock_split_left_gt_right.h +++ b/quantum/encoder/tests/config_mock_split_left_gt_right.h @@ -7,13 +7,13 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ { 0, 2, 4 } -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ { 1, 3, 5 } -#define ENCODERS_PAD_A_RIGHT \ +#define ENCODER_A_PINS_RIGHT \ { 6, 8 } -#define ENCODERS_PAD_B_RIGHT \ +#define ENCODER_B_PINS_RIGHT \ { 7, 9 } #ifdef __cplusplus diff --git a/quantum/encoder/tests/config_mock_split_left_lt_right.h b/quantum/encoder/tests/config_mock_split_left_lt_right.h index 075c774b0d..61808e866e 100644 --- a/quantum/encoder/tests/config_mock_split_left_lt_right.h +++ b/quantum/encoder/tests/config_mock_split_left_lt_right.h @@ -7,13 +7,13 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ { 0, 2 } -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ { 1, 3 } -#define ENCODERS_PAD_A_RIGHT \ +#define ENCODER_A_PINS_RIGHT \ { 4, 6, 8 } -#define ENCODERS_PAD_B_RIGHT \ +#define ENCODER_B_PINS_RIGHT \ { 5, 7, 9 } #ifdef __cplusplus diff --git a/quantum/encoder/tests/config_mock_split_no_left.h b/quantum/encoder/tests/config_mock_split_no_left.h index dfd8358929..599e584ff1 100644 --- a/quantum/encoder/tests/config_mock_split_no_left.h +++ b/quantum/encoder/tests/config_mock_split_no_left.h @@ -7,13 +7,13 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ {} -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ {} -#define ENCODERS_PAD_A_RIGHT \ +#define ENCODER_A_PINS_RIGHT \ { 0, 2 } -#define ENCODERS_PAD_B_RIGHT \ +#define ENCODER_B_PINS_RIGHT \ { 1, 3 } #ifdef __cplusplus diff --git a/quantum/encoder/tests/config_mock_split_no_right.h b/quantum/encoder/tests/config_mock_split_no_right.h index 5683eade8c..c3f753014c 100644 --- a/quantum/encoder/tests/config_mock_split_no_right.h +++ b/quantum/encoder/tests/config_mock_split_no_right.h @@ -7,13 +7,13 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ { 0, 2 } -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ { 1, 3 } -#define ENCODERS_PAD_A_RIGHT \ +#define ENCODER_A_PINS_RIGHT \ {} -#define ENCODERS_PAD_B_RIGHT \ +#define ENCODER_B_PINS_RIGHT \ {} #ifdef __cplusplus diff --git a/quantum/encoder/tests/config_mock_split_role.h b/quantum/encoder/tests/config_mock_split_role.h index ea795657ef..a4aa051ef1 100644 --- a/quantum/encoder/tests/config_mock_split_role.h +++ b/quantum/encoder/tests/config_mock_split_role.h @@ -7,13 +7,13 @@ #define MATRIX_COLS 1 /* Here, "pins" from 0 to 31 are allowed. */ -#define ENCODERS_PAD_A \ +#define ENCODER_A_PINS \ { 0, 2 } -#define ENCODERS_PAD_B \ +#define ENCODER_B_PINS \ { 1, 3 } -#define ENCODERS_PAD_A_RIGHT \ +#define ENCODER_A_PINS_RIGHT \ { 4, 6 } -#define ENCODERS_PAD_B_RIGHT \ +#define ENCODER_B_PINS_RIGHT \ { 5, 7 } #ifdef __cplusplus -- cgit v1.2.3 From f8596b40a4bb15a1881138baa8b8787277e2e622 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 3 Jul 2024 18:35:54 +1000 Subject: Normalise mouse keycodes (#23975) --- data/constants/keycodes/keycodes_0.0.5.hjson | 0 data/constants/keycodes/keycodes_0.0.5_basic.hjson | 175 +++++++++++++++++++++ docs/features/encoders.md | 8 +- docs/features/mouse_keys.md | 82 +++++----- docs/features/repeat_key.md | 8 +- docs/keycodes.md | 39 ++--- drivers/sensors/cirque_pinnacle_gestures.h | 2 +- .../lib/satisfaction75/satisfaction_encoder.c | 6 +- keyboards/dichotomy/keymaps/default/keymap.c | 16 +- quantum/action.c | 6 +- quantum/encoder.c | 4 +- quantum/keycode.h | 8 +- quantum/keycodes.h | 80 +++++----- quantum/mousekey.c | 112 ++++++------- quantum/pointing_device/pointing_device.c | 2 +- .../pointing_device/pointing_device_auto_mouse.h | 2 +- quantum/quantum_keycodes_legacy.h | 39 +++++ quantum/repeat_key.c | 8 +- tests/test_common/keycode_table.cpp | 38 ++--- 19 files changed, 426 insertions(+), 209 deletions(-) create mode 100644 data/constants/keycodes/keycodes_0.0.5.hjson create mode 100644 data/constants/keycodes/keycodes_0.0.5_basic.hjson (limited to 'docs/features') diff --git a/data/constants/keycodes/keycodes_0.0.5.hjson b/data/constants/keycodes/keycodes_0.0.5.hjson new file mode 100644 index 0000000000..e69de29bb2 diff --git a/data/constants/keycodes/keycodes_0.0.5_basic.hjson b/data/constants/keycodes/keycodes_0.0.5_basic.hjson new file mode 100644 index 0000000000..79b6bf6596 --- /dev/null +++ b/data/constants/keycodes/keycodes_0.0.5_basic.hjson @@ -0,0 +1,175 @@ +{ + "keycodes": { + "0x00CD": { + "group": "mouse", + "key": "QK_MOUSE_CURSOR_UP", + "label": "Mouse cursor up", + "aliases": [ + "!reset!", + "MS_UP" + ] + }, + "0x00CE": { + "group": "mouse", + "key": "QK_MOUSE_CURSOR_DOWN", + "label": "Mouse cursor down", + "aliases": [ + "!reset!", + "MS_DOWN" + ] + }, + "0x00CF": { + "group": "mouse", + "key": "QK_MOUSE_CURSOR_LEFT", + "label": "Mouse cursor left", + "aliases": [ + "!reset!", + "MS_LEFT" + ] + }, + "0x00D0": { + "group": "mouse", + "key": "QK_MOUSE_CURSOR_RIGHT", + "label": "Mouse cursor right", + "aliases": [ + "!reset!", + "MS_RGHT" + ] + }, + "0x00D1": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_1", + "label": "Mouse button 1", + "aliases": [ + "!reset!", + "MS_BTN1" + ] + }, + "0x00D2": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_2", + "label": "Mouse button 2", + "aliases": [ + "!reset!", + "MS_BTN2" + ] + }, + "0x00D3": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_3", + "label": "Mouse button 3", + "aliases": [ + "!reset!", + "MS_BTN3" + ] + }, + "0x00D4": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_4", + "label": "Mouse button 4", + "aliases": [ + "!reset!", + "MS_BTN4" + ] + }, + "0x00D5": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_5", + "label": "Mouse button 5", + "aliases": [ + "!reset!", + "MS_BTN5" + ] + }, + "0x00D6": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_6", + "label": "Mouse button 6", + "aliases": [ + "!reset!", + "MS_BTN6" + ] + }, + "0x00D7": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_7", + "label": "Mouse button 7", + "aliases": [ + "!reset!", + "MS_BTN7" + ] + }, + "0x00D8": { + "group": "mouse", + "key": "QK_MOUSE_BUTTON_8", + "label": "Mouse button 8", + "aliases": [ + "!reset!", + "MS_BTN8" + ] + }, + "0x00D9": { + "group": "mouse", + "key": "QK_MOUSE_WHEEL_UP", + "label": "Mouse wheel up", + "aliases": [ + "!reset!", + "MS_WHLU" + ] + }, + "0x00DA": { + "group": "mouse", + "key": "QK_MOUSE_WHEEL_DOWN", + "label": "Mouse wheel down", + "aliases": [ + "!reset!", + "MS_WHLD" + ] + }, + "0x00DB": { + "group": "mouse", + "key": "QK_MOUSE_WHEEL_LEFT", + "label": "Mouse wheel left", + "aliases": [ + "!reset!", + "MS_WHLL" + ] + }, + "0x00DC": { + "group": "mouse", + "key": "QK_MOUSE_WHEEL_RIGHT", + "label": "Mouse wheel right", + "aliases": [ + "!reset!", + "MS_WHLR" + ] + }, + "0x00DD": { + "group": "mouse", + "key": "QK_MOUSE_ACCELERATION_0", + "label": "Set mouse acceleration to 0", + "aliases": [ + "!reset!", + "MS_ACL0" + ] + }, + "0x00DE": { + "group": "mouse", + "key": "QK_MOUSE_ACCELERATION_1", + "label": "Set mouse acceleration to 1", + "aliases": [ + "!reset!", + "MS_ACL1" + ] + }, + "0x00DF": { + "group": "mouse", + "key": "QK_MOUSE_ACCELERATION_2", + "label": "Set mouse acceleration to 2", + "aliases": [ + "!reset!", + "MS_ACL2" + ] + } + } +} diff --git a/docs/features/encoders.md b/docs/features/encoders.md index eea70dafec..73cbb4f3f3 100644 --- a/docs/features/encoders.md +++ b/docs/features/encoders.md @@ -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(RGB_HUD, RGB_HUI), ENCODER_CCW_CW(RGB_SAD, RGB_SAI) }, - [2] = { ENCODER_CCW_CW(RGB_VAD, RGB_VAI), ENCODER_CCW_CW(RGB_SPD, RGB_SPI) }, - [3] = { ENCODER_CCW_CW(RGB_RMOD, RGB_MOD), 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(RGB_HUD, RGB_HUI), ENCODER_CCW_CW(RGB_SAD, RGB_SAI) }, + [2] = { ENCODER_CCW_CW(RGB_VAD, RGB_VAI), ENCODER_CCW_CW(RGB_SPD, RGB_SPI) }, + [3] = { ENCODER_CCW_CW(RGB_RMOD, RGB_MOD), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, }; #endif ``` 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/keycodes.md b/docs/keycodes.md index 4c91d98fa7..ea8b2e7b65 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -611,24 +611,27 @@ See also: [MIDI](features/midi) See also: [Mouse Keys](features/mouse_keys) -|Key |Aliases |Description | -|----------------|---------|---------------------------| -|`KC_MS_UP` |`KC_MS_U`|Mouse Cursor Up | -|`KC_MS_DOWN` |`KC_MS_D`|Mouse Cursor Down | -|`KC_MS_LEFT` |`KC_MS_L`|Mouse Cursor Left | -|`KC_MS_RIGHT` |`KC_MS_R`|Mouse Cursor Right | -|`KC_MS_BTN1` |`KC_BTN1`|Mouse Button 1 | -|`KC_MS_BTN2` |`KC_BTN2`|Mouse Button 2 | -|`KC_MS_BTN3` |`KC_BTN3`|Mouse Button 3 | -|`KC_MS_BTN4` |`KC_BTN4`|Mouse Button 4 | -|`KC_MS_BTN5` |`KC_BTN5`|Mouse Button 5 | -|`KC_MS_WH_UP` |`KC_WH_U`|Mouse Wheel Up | -|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down | -|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left | -|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right | -|`KC_MS_ACCEL0` |`KC_ACL0`|Set mouse acceleration to 0| -|`KC_MS_ACCEL1` |`KC_ACL1`|Set mouse acceleration to 1| -|`KC_MS_ACCEL2` |`KC_ACL2`|Set mouse acceleration 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| ## Modifiers {#modifiers} diff --git a/drivers/sensors/cirque_pinnacle_gestures.h b/drivers/sensors/cirque_pinnacle_gestures.h index d2aa206b2b..1412c86f7e 100644 --- a/drivers/sensors/cirque_pinnacle_gestures.h +++ b/drivers/sensors/cirque_pinnacle_gestures.h @@ -28,7 +28,7 @@ typedef struct { # ifndef CIRQUE_PINNACLE_TAPPING_TERM # include "action.h" # include "action_tapping.h" -# define CIRQUE_PINNACLE_TAPPING_TERM GET_TAPPING_TERM(KC_BTN1, &(keyrecord_t){}) +# define CIRQUE_PINNACLE_TAPPING_TERM GET_TAPPING_TERM(QK_MOUSE_BUTTON_1, &(keyrecord_t){}) # endif # ifndef CIRQUE_PINNACLE_TOUCH_DEBOUNCE # define CIRQUE_PINNACLE_TOUCH_DEBOUNCE (CIRQUE_PINNACLE_TAPPING_TERM * 8) diff --git a/keyboards/cannonkeys/lib/satisfaction75/satisfaction_encoder.c b/keyboards/cannonkeys/lib/satisfaction75/satisfaction_encoder.c index aab005ebd8..7e0b82e9e7 100644 --- a/keyboards/cannonkeys/lib/satisfaction75/satisfaction_encoder.c +++ b/keyboards/cannonkeys/lib/satisfaction75/satisfaction_encoder.c @@ -101,7 +101,7 @@ uint16_t handle_encoder_clockwise(void){ mapped_code = KC_MEDIA_NEXT_TRACK; break; case ENC_MODE_SCROLL: - mapped_code = KC_WH_D; + mapped_code = QK_MOUSE_WHEEL_DOWN; break; #ifdef BACKLIGHT_ENABLE case ENC_MODE_BACKLIGHT: @@ -143,7 +143,7 @@ uint16_t handle_encoder_ccw(void){ mapped_code = KC_MEDIA_PREV_TRACK; break; case ENC_MODE_SCROLL: - mapped_code = KC_WH_U; + mapped_code = QK_MOUSE_WHEEL_UP; break; #ifdef BACKLIGHT_ENABLE case ENC_MODE_BACKLIGHT: @@ -186,7 +186,7 @@ uint16_t handle_encoder_press(void){ mapped_code = KC_MEDIA_PLAY_PAUSE; break; case ENC_MODE_SCROLL: - mapped_code = KC_BTN3; + mapped_code = QK_MOUSE_BUTTON_3; break; #ifdef BACKLIGHT_ENABLE case ENC_MODE_BACKLIGHT: diff --git a/keyboards/dichotomy/keymaps/default/keymap.c b/keyboards/dichotomy/keymaps/default/keymap.c index b83f7b82e9..b92beb73cc 100755 --- a/keyboards/dichotomy/keymaps/default/keymap.c +++ b/keyboards/dichotomy/keymaps/default/keymap.c @@ -28,9 +28,9 @@ enum dichotomy_keycodes NUMKEY, SFTKEY, MOUKEY, - MS_BTN1, - MS_BTN2, - MS_BTN3 + CK_MSE1, + CK_MSE2, + CK_MSE3 }; #define CUSTOM_LONGPRESS 150 @@ -46,7 +46,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { NUMKEY, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, CK_QE, SFTKEY, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, MOUKEY, KC_LCTL, KC_LALT, KC_LGUI, KC_RGUI, KC_RALT, KC_RCTL, - MS_BTN3, KC_LBRC, KC_LPRN, KC_SPC, KC_SPC, KC_RPRN, KC_RBRC, MS_BTN3 + CK_MSE3, KC_LBRC, KC_LPRN, KC_SPC, KC_SPC, KC_RPRN, KC_RBRC, CK_MSE3 ), [_SF] = LAYOUT( /* Shifted layout, small changes (because angle brackets have been moved to thumb cluster buttons) */ @@ -75,7 +75,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [_MS] = LAYOUT( /* Mouse layer, including buttons for clicking. */ _______, _______, _______, _______, _______, _______, KC_VOLU, KC_HOME, KC_PGUP, _______, _______, _______, - _______, _______, _______, _______, _______, _______, _______, MS_BTN1, MS_BTN2, _______, _______, _______, + _______, _______, _______, _______, _______, _______, _______, CK_MSE1, CK_MSE2, _______, _______, _______, _______, _______, _______, _______, _______, _______, KC_VOLD, KC_END, KC_PGDN, _______, _______, _______, _______, _______, _______, _______, KC_UP, _______, _______, _______, _______, _______, KC_LEFT, KC_DOWN, KC_RGHT, _______ @@ -311,7 +311,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { break; //mouse buttons, for 1-3, to update the mouse report: - case MS_BTN1: + case CK_MSE1: currentReport = pointing_device_get_report(); if (record->event.pressed) { if (shift_held && shift_suspended){ @@ -327,7 +327,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { pointing_device_set_report(currentReport); returnVal = false; break; - case MS_BTN2: + case CK_MSE2: currentReport = pointing_device_get_report(); if (record->event.pressed) { if (shift_held && shift_suspended){ @@ -343,7 +343,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { pointing_device_set_report(currentReport); returnVal = false; break; - case MS_BTN3: + case CK_MSE3: currentReport = pointing_device_get_report(); if (record->event.pressed) { if (shift_held && shift_suspended){ diff --git a/quantum/action.c b/quantum/action.c index 74ef55e5eb..a39631ba3e 100644 --- a/quantum/action.c +++ b/quantum/action.c @@ -329,7 +329,7 @@ void register_mouse(uint8_t mouse_keycode, bool pressed) { // should mousekeys send report, or does something else handle this? switch (mouse_keycode) { # if defined(PS2_MOUSE_ENABLE) || defined(POINTING_DEVICE_ENABLE) - case KC_MS_BTN1 ... KC_MS_BTN8: + case QK_MOUSE_BUTTON_1 ... QK_MOUSE_BUTTON_8: // let pointing device handle the buttons // expand if/when it handles more of the code # if defined(POINTING_DEVICE_ENABLE) @@ -351,8 +351,8 @@ void register_mouse(uint8_t mouse_keycode, bool pressed) { #ifdef PS2_MOUSE_ENABLE // make sure that ps2 mouse has button report synced - if (KC_MS_BTN1 <= mouse_keycode && mouse_keycode <= KC_MS_BTN3) { - uint8_t tmp_button_msk = MOUSE_BTN_MASK(mouse_keycode - KC_MS_BTN1); + if (QK_MOUSE_BUTTON_1 <= mouse_keycode && mouse_keycode <= QK_MOUSE_BUTTON_3) { + uint8_t tmp_button_msk = MOUSE_BTN_MASK(mouse_keycode - QK_MOUSE_BUTTON_1); tp_buttons = pressed ? tp_buttons | tmp_button_msk : tp_buttons & ~tmp_button_msk; } #endif diff --git a/quantum/encoder.c b/quantum/encoder.c index 2ddbf3ee1e..27d7b1fc80 100644 --- a/quantum/encoder.c +++ b/quantum/encoder.c @@ -160,7 +160,7 @@ __attribute__((weak)) bool encoder_update_kb(uint8_t index, bool clockwise) { # if defined(EXTRAKEY_ENABLE) tap_code_delay(KC_VOLU, 10); # elif defined(MOUSEKEY_ENABLE) - tap_code_delay(KC_MS_WH_UP, 10); + tap_code_delay(QK_MOUSE_WHEEL_UP, 10); # else tap_code_delay(KC_PGDN, 10); # endif @@ -168,7 +168,7 @@ __attribute__((weak)) bool encoder_update_kb(uint8_t index, bool clockwise) { # if defined(EXTRAKEY_ENABLE) tap_code_delay(KC_VOLD, 10); # elif defined(MOUSEKEY_ENABLE) - tap_code_delay(KC_MS_WH_DOWN, 10); + tap_code_delay(QK_MOUSE_WHEEL_DOWN, 10); # else tap_code_delay(KC_PGUP, 10); # endif diff --git a/quantum/keycode.h b/quantum/keycode.h index df1452d296..4ff6894a01 100644 --- a/quantum/keycode.h +++ b/quantum/keycode.h @@ -29,10 +29,10 @@ along with this program. If not, see . #define IS_ANY(code) (KC_A <= (code) && (code) <= 0xFF) #define IS_MOUSEKEY(code) IS_MOUSE_KEYCODE(code) -#define IS_MOUSEKEY_MOVE(code) (KC_MS_UP <= (code) && (code) <= KC_MS_RIGHT) -#define IS_MOUSEKEY_BUTTON(code) (KC_MS_BTN1 <= (code) && (code) <= KC_MS_BTN8) -#define IS_MOUSEKEY_WHEEL(code) (KC_MS_WH_UP <= (code) && (code) <= KC_MS_WH_RIGHT) -#define IS_MOUSEKEY_ACCEL(code) (KC_MS_ACCEL0 <= (code) && (code) <= KC_MS_ACCEL2) +#define IS_MOUSEKEY_MOVE(code) (QK_MOUSE_CURSOR_UP <= (code) && (code) <= QK_MOUSE_CURSOR_RIGHT) +#define IS_MOUSEKEY_BUTTON(code) (QK_MOUSE_BUTTON_1 <= (code) && (code) <= QK_MOUSE_BUTTON_8) +#define IS_MOUSEKEY_WHEEL(code) (QK_MOUSE_WHEEL_UP <= (code) && (code) <= QK_MOUSE_WHEEL_RIGHT) +#define IS_MOUSEKEY_ACCEL(code) (QK_MOUSE_ACCELERATION_0 <= (code) && (code) <= QK_MOUSE_ACCELERATION_2) #define MOD_BIT(code) (1 << ((code)&0x07)) diff --git a/quantum/keycodes.h b/quantum/keycodes.h index c92028ab43..f461e4a586 100644 --- a/quantum/keycodes.h +++ b/quantum/keycodes.h @@ -283,25 +283,25 @@ enum qk_keycode_defines { KC_ASSISTANT = 0x00C0, KC_MISSION_CONTROL = 0x00C1, KC_LAUNCHPAD = 0x00C2, - KC_MS_UP = 0x00CD, - KC_MS_DOWN = 0x00CE, - KC_MS_LEFT = 0x00CF, - KC_MS_RIGHT = 0x00D0, - KC_MS_BTN1 = 0x00D1, - KC_MS_BTN2 = 0x00D2, - KC_MS_BTN3 = 0x00D3, - KC_MS_BTN4 = 0x00D4, - KC_MS_BTN5 = 0x00D5, - KC_MS_BTN6 = 0x00D6, - KC_MS_BTN7 = 0x00D7, - KC_MS_BTN8 = 0x00D8, - KC_MS_WH_UP = 0x00D9, - KC_MS_WH_DOWN = 0x00DA, - KC_MS_WH_LEFT = 0x00DB, - KC_MS_WH_RIGHT = 0x00DC, - KC_MS_ACCEL0 = 0x00DD, - KC_MS_ACCEL1 = 0x00DE, - KC_MS_ACCEL2 = 0x00DF, + QK_MOUSE_CURSOR_UP = 0x00CD, + QK_MOUSE_CURSOR_DOWN = 0x00CE, + QK_MOUSE_CURSOR_LEFT = 0x00CF, + QK_MOUSE_CURSOR_RIGHT = 0x00D0, + QK_MOUSE_BUTTON_1 = 0x00D1, + QK_MOUSE_BUTTON_2 = 0x00D2, + QK_MOUSE_BUTTON_3 = 0x00D3, + QK_MOUSE_BUTTON_4 = 0x00D4, + QK_MOUSE_BUTTON_5 = 0x00D5, + QK_MOUSE_BUTTON_6 = 0x00D6, + QK_MOUSE_BUTTON_7 = 0x00D7, + QK_MOUSE_BUTTON_8 = 0x00D8, + QK_MOUSE_WHEEL_UP = 0x00D9, + QK_MOUSE_WHEEL_DOWN = 0x00DA, + QK_MOUSE_WHEEL_LEFT = 0x00DB, + QK_MOUSE_WHEEL_RIGHT = 0x00DC, + QK_MOUSE_ACCELERATION_0 = 0x00DD, + QK_MOUSE_ACCELERATION_1 = 0x00DE, + QK_MOUSE_ACCELERATION_2 = 0x00DF, KC_LEFT_CTRL = 0x00E0, KC_LEFT_SHIFT = 0x00E1, KC_LEFT_ALT = 0x00E2, @@ -926,25 +926,25 @@ enum qk_keycode_defines { KC_ASST = KC_ASSISTANT, KC_MCTL = KC_MISSION_CONTROL, KC_LPAD = KC_LAUNCHPAD, - KC_MS_U = KC_MS_UP, - KC_MS_D = KC_MS_DOWN, - KC_MS_L = KC_MS_LEFT, - KC_MS_R = KC_MS_RIGHT, - KC_BTN1 = KC_MS_BTN1, - KC_BTN2 = KC_MS_BTN2, - KC_BTN3 = KC_MS_BTN3, - KC_BTN4 = KC_MS_BTN4, - KC_BTN5 = KC_MS_BTN5, - KC_BTN6 = KC_MS_BTN6, - KC_BTN7 = KC_MS_BTN7, - KC_BTN8 = KC_MS_BTN8, - KC_WH_U = KC_MS_WH_UP, - KC_WH_D = KC_MS_WH_DOWN, - KC_WH_L = KC_MS_WH_LEFT, - KC_WH_R = KC_MS_WH_RIGHT, - KC_ACL0 = KC_MS_ACCEL0, - KC_ACL1 = KC_MS_ACCEL1, - KC_ACL2 = KC_MS_ACCEL2, + MS_UP = QK_MOUSE_CURSOR_UP, + MS_DOWN = QK_MOUSE_CURSOR_DOWN, + MS_LEFT = QK_MOUSE_CURSOR_LEFT, + MS_RGHT = QK_MOUSE_CURSOR_RIGHT, + MS_BTN1 = QK_MOUSE_BUTTON_1, + MS_BTN2 = QK_MOUSE_BUTTON_2, + MS_BTN3 = QK_MOUSE_BUTTON_3, + MS_BTN4 = QK_MOUSE_BUTTON_4, + MS_BTN5 = QK_MOUSE_BUTTON_5, + MS_BTN6 = QK_MOUSE_BUTTON_6, + MS_BTN7 = QK_MOUSE_BUTTON_7, + MS_BTN8 = QK_MOUSE_BUTTON_8, + MS_WHLU = QK_MOUSE_WHEEL_UP, + MS_WHLD = QK_MOUSE_WHEEL_DOWN, + MS_WHLL = QK_MOUSE_WHEEL_LEFT, + MS_WHLR = QK_MOUSE_WHEEL_RIGHT, + MS_ACL0 = QK_MOUSE_ACCELERATION_0, + MS_ACL1 = QK_MOUSE_ACCELERATION_1, + MS_ACL2 = QK_MOUSE_ACCELERATION_2, KC_LCTL = KC_LEFT_CTRL, KC_LSFT = KC_LEFT_SHIFT, KC_LALT = KC_LEFT_ALT, @@ -1457,7 +1457,7 @@ enum qk_keycode_defines { #define IS_BASIC_KEYCODE(code) ((code) >= KC_A && (code) <= KC_EXSEL) #define IS_SYSTEM_KEYCODE(code) ((code) >= KC_SYSTEM_POWER && (code) <= KC_SYSTEM_WAKE) #define IS_CONSUMER_KEYCODE(code) ((code) >= KC_AUDIO_MUTE && (code) <= KC_LAUNCHPAD) -#define IS_MOUSE_KEYCODE(code) ((code) >= KC_MS_UP && (code) <= KC_MS_ACCEL2) +#define IS_MOUSE_KEYCODE(code) ((code) >= QK_MOUSE_CURSOR_UP && (code) <= QK_MOUSE_ACCELERATION_2) #define IS_MODIFIER_KEYCODE(code) ((code) >= KC_LEFT_CTRL && (code) <= KC_RIGHT_GUI) #define IS_SWAP_HANDS_KEYCODE(code) ((code) >= QK_SWAP_HANDS_TOGGLE && (code) <= QK_SWAP_HANDS_ONE_SHOT) #define IS_MAGIC_KEYCODE(code) ((code) >= QK_MAGIC_SWAP_CONTROL_CAPS_LOCK && (code) <= QK_MAGIC_TOGGLE_ESCAPE_CAPS_LOCK) @@ -1482,7 +1482,7 @@ enum qk_keycode_defines { #define BASIC_KEYCODE_RANGE KC_A ... KC_EXSEL #define SYSTEM_KEYCODE_RANGE KC_SYSTEM_POWER ... KC_SYSTEM_WAKE #define CONSUMER_KEYCODE_RANGE KC_AUDIO_MUTE ... KC_LAUNCHPAD -#define MOUSE_KEYCODE_RANGE KC_MS_UP ... KC_MS_ACCEL2 +#define MOUSE_KEYCODE_RANGE QK_MOUSE_CURSOR_UP ... QK_MOUSE_ACCELERATION_2 #define MODIFIER_KEYCODE_RANGE KC_LEFT_CTRL ... KC_RIGHT_GUI #define SWAP_HANDS_KEYCODE_RANGE QK_SWAP_HANDS_TOGGLE ... QK_SWAP_HANDS_ONE_SHOT #define MAGIC_KEYCODE_RANGE QK_MAGIC_SWAP_CONTROL_CAPS_LOCK ... QK_MAGIC_TOGGLE_ESCAPE_CAPS_LOCK diff --git a/quantum/mousekey.c b/quantum/mousekey.c index 3910811752..8683cfdffa 100644 --- a/quantum/mousekey.c +++ b/quantum/mousekey.c @@ -407,42 +407,42 @@ void mousekey_on(uint8_t code) { # ifdef MOUSEKEY_INERTIA // initial keypress sets impulse and activates first frame of movement - if ((code == KC_MS_UP) || (code == KC_MS_DOWN)) { - mousekey_y_dir = (code == KC_MS_DOWN) ? 1 : -1; + if ((code == QK_MOUSE_CURSOR_UP) || (code == QK_MOUSE_CURSOR_DOWN)) { + mousekey_y_dir = (code == QK_MOUSE_CURSOR_DOWN) ? 1 : -1; if (mousekey_frame < 2) mouse_report.y = move_unit(1); - } else if ((code == KC_MS_LEFT) || (code == KC_MS_RIGHT)) { - mousekey_x_dir = (code == KC_MS_RIGHT) ? 1 : -1; + } else if ((code == QK_MOUSE_CURSOR_LEFT) || (code == QK_MOUSE_CURSOR_RIGHT)) { + mousekey_x_dir = (code == QK_MOUSE_CURSOR_RIGHT) ? 1 : -1; if (mousekey_frame < 2) mouse_report.x = move_unit(0); } # else // no inertia - if (code == KC_MS_UP) + if (code == QK_MOUSE_CURSOR_UP) mouse_report.y = move_unit() * -1; - else if (code == KC_MS_DOWN) + else if (code == QK_MOUSE_CURSOR_DOWN) mouse_report.y = move_unit(); - else if (code == KC_MS_LEFT) + else if (code == QK_MOUSE_CURSOR_LEFT) mouse_report.x = move_unit() * -1; - else if (code == KC_MS_RIGHT) + else if (code == QK_MOUSE_CURSOR_RIGHT) mouse_report.x = move_unit(); # endif // inertia or not - else if (code == KC_MS_WH_UP) + else if (code == QK_MOUSE_WHEEL_UP) mouse_report.v = wheel_unit(); - else if (code == KC_MS_WH_DOWN) + else if (code == QK_MOUSE_WHEEL_DOWN) mouse_report.v = wheel_unit() * -1; - else if (code == KC_MS_WH_LEFT) + else if (code == QK_MOUSE_WHEEL_LEFT) mouse_report.h = wheel_unit() * -1; - else if (code == KC_MS_WH_RIGHT) + else if (code == QK_MOUSE_WHEEL_RIGHT) mouse_report.h = wheel_unit(); else if (IS_MOUSEKEY_BUTTON(code)) - mouse_report.buttons |= 1 << (code - KC_MS_BTN1); - else if (code == KC_MS_ACCEL0) + mouse_report.buttons |= 1 << (code - QK_MOUSE_BUTTON_1); + else if (code == QK_MOUSE_ACCELERATION_0) mousekey_accel |= (1 << 0); - else if (code == KC_MS_ACCEL1) + else if (code == QK_MOUSE_ACCELERATION_1) mousekey_accel |= (1 << 1); - else if (code == KC_MS_ACCEL2) + else if (code == QK_MOUSE_ACCELERATION_2) mousekey_accel |= (1 << 2); } @@ -450,43 +450,43 @@ void mousekey_off(uint8_t code) { # ifdef MOUSEKEY_INERTIA // key release clears impulse unless opposite direction is held - if ((code == KC_MS_UP) && (mousekey_y_dir < 1)) + if ((code == QK_MOUSE_CURSOR_UP) && (mousekey_y_dir < 1)) mousekey_y_dir = 0; - else if ((code == KC_MS_DOWN) && (mousekey_y_dir > -1)) + else if ((code == QK_MOUSE_CURSOR_DOWN) && (mousekey_y_dir > -1)) mousekey_y_dir = 0; - else if ((code == KC_MS_LEFT) && (mousekey_x_dir < 1)) + else if ((code == QK_MOUSE_CURSOR_LEFT) && (mousekey_x_dir < 1)) mousekey_x_dir = 0; - else if ((code == KC_MS_RIGHT) && (mousekey_x_dir > -1)) + else if ((code == QK_MOUSE_CURSOR_RIGHT) && (mousekey_x_dir > -1)) mousekey_x_dir = 0; # else // no inertia - if (code == KC_MS_UP && mouse_report.y < 0) + if (code == QK_MOUSE_CURSOR_UP && mouse_report.y < 0) mouse_report.y = 0; - else if (code == KC_MS_DOWN && mouse_report.y > 0) + else if (code == QK_MOUSE_CURSOR_DOWN && mouse_report.y > 0) mouse_report.y = 0; - else if (code == KC_MS_LEFT && mouse_report.x < 0) + else if (code == QK_MOUSE_CURSOR_LEFT && mouse_report.x < 0) mouse_report.x = 0; - else if (code == KC_MS_RIGHT && mouse_report.x > 0) + else if (code == QK_MOUSE_CURSOR_RIGHT && mouse_report.x > 0) mouse_report.x = 0; # endif // inertia or not - else if (code == KC_MS_WH_UP && mouse_report.v > 0) + else if (code == QK_MOUSE_WHEEL_UP && mouse_report.v > 0) mouse_report.v = 0; - else if (code == KC_MS_WH_DOWN && mouse_report.v < 0) + else if (code == QK_MOUSE_WHEEL_DOWN && mouse_report.v < 0) mouse_report.v = 0; - else if (code == KC_MS_WH_LEFT && mouse_report.h < 0) + else if (code == QK_MOUSE_WHEEL_LEFT && mouse_report.h < 0) mouse_report.h = 0; - else if (code == KC_MS_WH_RIGHT && mouse_report.h > 0) + else if (code == QK_MOUSE_WHEEL_RIGHT && mouse_report.h > 0) mouse_report.h = 0; else if (IS_MOUSEKEY_BUTTON(code)) - mouse_report.buttons &= ~(1 << (code - KC_MS_BTN1)); - else if (code == KC_MS_ACCEL0) + mouse_report.buttons &= ~(1 << (code - QK_MOUSE_BUTTON_1)); + else if (code == QK_MOUSE_ACCELERATION_0) mousekey_accel &= ~(1 << 0); - else if (code == KC_MS_ACCEL1) + else if (code == QK_MOUSE_ACCELERATION_1) mousekey_accel &= ~(1 << 1); - else if (code == KC_MS_ACCEL2) + else if (code == QK_MOUSE_ACCELERATION_2) mousekey_accel &= ~(1 << 2); if (mouse_report.x == 0 && mouse_report.y == 0) { mousekey_repeat = 0; @@ -568,29 +568,29 @@ void mousekey_on(uint8_t code) { uint16_t const c_offset = c_offsets[mk_speed]; uint16_t const w_offset = w_offsets[mk_speed]; uint8_t const old_speed = mk_speed; - if (code == KC_MS_UP) + if (code == QK_MOUSE_CURSOR_UP) mouse_report.y = c_offset * -1; - else if (code == KC_MS_DOWN) + else if (code == QK_MOUSE_CURSOR_DOWN) mouse_report.y = c_offset; - else if (code == KC_MS_LEFT) + else if (code == QK_MOUSE_CURSOR_LEFT) mouse_report.x = c_offset * -1; - else if (code == KC_MS_RIGHT) + else if (code == QK_MOUSE_CURSOR_RIGHT) mouse_report.x = c_offset; - else if (code == KC_MS_WH_UP) + else if (code == QK_MOUSE_WHEEL_UP) mouse_report.v = w_offset; - else if (code == KC_MS_WH_DOWN) + else if (code == QK_MOUSE_WHEEL_DOWN) mouse_report.v = w_offset * -1; - else if (code == KC_MS_WH_LEFT) + else if (code == QK_MOUSE_WHEEL_LEFT) mouse_report.h = w_offset * -1; - else if (code == KC_MS_WH_RIGHT) + else if (code == QK_MOUSE_WHEEL_RIGHT) mouse_report.h = w_offset; else if (IS_MOUSEKEY_BUTTON(code)) - mouse_report.buttons |= 1 << (code - KC_MS_BTN1); - else if (code == KC_MS_ACCEL0) + mouse_report.buttons |= 1 << (code - QK_MOUSE_BUTTON_1); + else if (code == QK_MOUSE_ACCELERATION_0) mk_speed = mkspd_0; - else if (code == KC_MS_ACCEL1) + else if (code == QK_MOUSE_ACCELERATION_1) mk_speed = mkspd_1; - else if (code == KC_MS_ACCEL2) + else if (code == QK_MOUSE_ACCELERATION_2) mk_speed = mkspd_2; if (mk_speed != old_speed) adjust_speed(); } @@ -599,30 +599,30 @@ void mousekey_off(uint8_t code) { # ifdef MK_MOMENTARY_ACCEL uint8_t const old_speed = mk_speed; # endif - if (code == KC_MS_UP && mouse_report.y < 0) + if (code == QK_MOUSE_CURSOR_UP && mouse_report.y < 0) mouse_report.y = 0; - else if (code == KC_MS_DOWN && mouse_report.y > 0) + else if (code == QK_MOUSE_CURSOR_DOWN && mouse_report.y > 0) mouse_report.y = 0; - else if (code == KC_MS_LEFT && mouse_report.x < 0) + else if (code == QK_MOUSE_CURSOR_LEFT && mouse_report.x < 0) mouse_report.x = 0; - else if (code == KC_MS_RIGHT && mouse_report.x > 0) + else if (code == QK_MOUSE_CURSOR_RIGHT && mouse_report.x > 0) mouse_report.x = 0; - else if (code == KC_MS_WH_UP && mouse_report.v > 0) + else if (code == QK_MOUSE_WHEEL_UP && mouse_report.v > 0) mouse_report.v = 0; - else if (code == KC_MS_WH_DOWN && mouse_report.v < 0) + else if (code == QK_MOUSE_WHEEL_DOWN && mouse_report.v < 0) mouse_report.v = 0; - else if (code == KC_MS_WH_LEFT && mouse_report.h < 0) + else if (code == QK_MOUSE_WHEEL_LEFT && mouse_report.h < 0) mouse_report.h = 0; - else if (code == KC_MS_WH_RIGHT && mouse_report.h > 0) + else if (code == QK_MOUSE_WHEEL_RIGHT && mouse_report.h > 0) mouse_report.h = 0; else if (IS_MOUSEKEY_BUTTON(code)) - mouse_report.buttons &= ~(1 << (code - KC_MS_BTN1)); + mouse_report.buttons &= ~(1 << (code - QK_MOUSE_BUTTON_1)); # ifdef MK_MOMENTARY_ACCEL - else if (code == KC_MS_ACCEL0) + else if (code == QK_MOUSE_ACCELERATION_0) mk_speed = mkspd_DEFAULT; - else if (code == KC_MS_ACCEL1) + else if (code == QK_MOUSE_ACCELERATION_1) mk_speed = mkspd_DEFAULT; - else if (code == KC_MS_ACCEL2) + else if (code == QK_MOUSE_ACCELERATION_2) mk_speed = mkspd_DEFAULT; if (mk_speed != old_speed) adjust_speed(); # endif diff --git a/quantum/pointing_device/pointing_device.c b/quantum/pointing_device/pointing_device.c index 4682aceb14..74ce9108a9 100644 --- a/quantum/pointing_device/pointing_device.c +++ b/quantum/pointing_device/pointing_device.c @@ -498,7 +498,7 @@ __attribute__((weak)) report_mouse_t pointing_device_task_combined_user(report_m __attribute__((weak)) void pointing_device_keycode_handler(uint16_t keycode, bool pressed) { if IS_MOUSEKEY_BUTTON (keycode) { - local_mouse_report.buttons = pointing_device_handle_buttons(local_mouse_report.buttons, pressed, keycode - KC_MS_BTN1); + local_mouse_report.buttons = pointing_device_handle_buttons(local_mouse_report.buttons, pressed, keycode - QK_MOUSE_BUTTON_1); pointing_device_send(); } } diff --git a/quantum/pointing_device/pointing_device_auto_mouse.h b/quantum/pointing_device/pointing_device_auto_mouse.h index a596c065a3..2c0d4d1043 100644 --- a/quantum/pointing_device/pointing_device_auto_mouse.h +++ b/quantum/pointing_device/pointing_device_auto_mouse.h @@ -37,7 +37,7 @@ # define AUTO_MOUSE_TIME 650 #endif #ifndef AUTO_MOUSE_DELAY -# define AUTO_MOUSE_DELAY GET_TAPPING_TERM(KC_MS_BTN1, &(keyrecord_t){}) +# define AUTO_MOUSE_DELAY GET_TAPPING_TERM(QK_MOUSE_BUTTON_1, &(keyrecord_t){}) #endif #ifndef AUTO_MOUSE_DEBOUNCE # define AUTO_MOUSE_DEBOUNCE 25 diff --git a/quantum/quantum_keycodes_legacy.h b/quantum/quantum_keycodes_legacy.h index 6ea5e13f3a..e1562077e5 100644 --- a/quantum/quantum_keycodes_legacy.h +++ b/quantum/quantum_keycodes_legacy.h @@ -16,3 +16,42 @@ #define RGB_VAD QK_UNDERGLOW_VALUE_DOWN #define RGB_SPI QK_UNDERGLOW_SPEED_UP #define RGB_SPD QK_UNDERGLOW_SPEED_DOWN + +#define KC_MS_UP QK_MOUSE_CURSOR_UP +#define KC_MS_U QK_MOUSE_CURSOR_UP +#define KC_MS_DOWN QK_MOUSE_CURSOR_DOWN +#define KC_MS_D QK_MOUSE_CURSOR_DOWN +#define KC_MS_LEFT QK_MOUSE_CURSOR_LEFT +#define KC_MS_L QK_MOUSE_CURSOR_LEFT +#define KC_MS_RIGHT QK_MOUSE_CURSOR_RIGHT +#define KC_MS_R QK_MOUSE_CURSOR_RIGHT +#define KC_MS_BTN1 QK_MOUSE_BUTTON_1 +#define KC_BTN1 QK_MOUSE_BUTTON_1 +#define KC_MS_BTN2 QK_MOUSE_BUTTON_2 +#define KC_BTN2 QK_MOUSE_BUTTON_2 +#define KC_MS_BTN3 QK_MOUSE_BUTTON_3 +#define KC_BTN3 QK_MOUSE_BUTTON_3 +#define KC_MS_BTN4 QK_MOUSE_BUTTON_4 +#define KC_BTN4 QK_MOUSE_BUTTON_4 +#define KC_MS_BTN5 QK_MOUSE_BUTTON_5 +#define KC_BTN5 QK_MOUSE_BUTTON_5 +#define KC_MS_BTN6 QK_MOUSE_BUTTON_6 +#define KC_BTN6 QK_MOUSE_BUTTON_6 +#define KC_MS_BTN7 QK_MOUSE_BUTTON_7 +#define KC_BTN7 QK_MOUSE_BUTTON_7 +#define KC_MS_BTN8 QK_MOUSE_BUTTON_8 +#define KC_BTN8 QK_MOUSE_BUTTON_8 +#define KC_MS_WH_UP QK_MOUSE_WHEEL_UP +#define KC_WH_U QK_MOUSE_WHEEL_UP +#define KC_MS_WH_DOWN QK_MOUSE_WHEEL_DOWN +#define KC_WH_D QK_MOUSE_WHEEL_DOWN +#define KC_MS_WH_LEFT QK_MOUSE_WHEEL_LEFT +#define KC_WH_L QK_MOUSE_WHEEL_LEFT +#define KC_MS_WH_RIGHT QK_MOUSE_WHEEL_RIGHT +#define KC_WH_R QK_MOUSE_WHEEL_RIGHT +#define KC_MS_ACCEL0 QK_MOUSE_ACCELERATION_0 +#define KC_ACL0 QK_MOUSE_ACCELERATION_0 +#define KC_MS_ACCEL1 QK_MOUSE_ACCELERATION_1 +#define KC_ACL1 QK_MOUSE_ACCELERATION_1 +#define KC_MS_ACCEL2 QK_MOUSE_ACCELERATION_2 +#define KC_ACL2 QK_MOUSE_ACCELERATION_2 diff --git a/quantum/repeat_key.c b/quantum/repeat_key.c index 4567428723..56f242f8b8 100644 --- a/quantum/repeat_key.c +++ b/quantum/repeat_key.c @@ -220,10 +220,10 @@ uint16_t get_alt_repeat_key_keycode(void) { {KC_BRIU, KC_BRID}, // Brightness Up / Down. #endif // EXTRAKEY_ENABLE #ifdef MOUSEKEY_ENABLE - {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. #endif // MOUSEKEY_ENABLE }; // clang-format on diff --git a/tests/test_common/keycode_table.cpp b/tests/test_common/keycode_table.cpp index 18dd536027..4c28ab4d20 100644 --- a/tests/test_common/keycode_table.cpp +++ b/tests/test_common/keycode_table.cpp @@ -225,25 +225,25 @@ std::map KEYCODE_ID_TABLE = { {KC_ASSISTANT, "KC_ASSISTANT"}, {KC_MISSION_CONTROL, "KC_MISSION_CONTROL"}, {KC_LAUNCHPAD, "KC_LAUNCHPAD"}, - {KC_MS_UP, "KC_MS_UP"}, - {KC_MS_DOWN, "KC_MS_DOWN"}, - {KC_MS_LEFT, "KC_MS_LEFT"}, - {KC_MS_RIGHT, "KC_MS_RIGHT"}, - {KC_MS_BTN1, "KC_MS_BTN1"}, - {KC_MS_BTN2, "KC_MS_BTN2"}, - {KC_MS_BTN3, "KC_MS_BTN3"}, - {KC_MS_BTN4, "KC_MS_BTN4"}, - {KC_MS_BTN5, "KC_MS_BTN5"}, - {KC_MS_BTN6, "KC_MS_BTN6"}, - {KC_MS_BTN7, "KC_MS_BTN7"}, - {KC_MS_BTN8, "KC_MS_BTN8"}, - {KC_MS_WH_UP, "KC_MS_WH_UP"}, - {KC_MS_WH_DOWN, "KC_MS_WH_DOWN"}, - {KC_MS_WH_LEFT, "KC_MS_WH_LEFT"}, - {KC_MS_WH_RIGHT, "KC_MS_WH_RIGHT"}, - {KC_MS_ACCEL0, "KC_MS_ACCEL0"}, - {KC_MS_ACCEL1, "KC_MS_ACCEL1"}, - {KC_MS_ACCEL2, "KC_MS_ACCEL2"}, + {QK_MOUSE_CURSOR_UP, "QK_MOUSE_CURSOR_UP"}, + {QK_MOUSE_CURSOR_DOWN, "QK_MOUSE_CURSOR_DOWN"}, + {QK_MOUSE_CURSOR_LEFT, "QK_MOUSE_CURSOR_LEFT"}, + {QK_MOUSE_CURSOR_RIGHT, "QK_MOUSE_CURSOR_RIGHT"}, + {QK_MOUSE_BUTTON_1, "QK_MOUSE_BUTTON_1"}, + {QK_MOUSE_BUTTON_2, "QK_MOUSE_BUTTON_2"}, + {QK_MOUSE_BUTTON_3, "QK_MOUSE_BUTTON_3"}, + {QK_MOUSE_BUTTON_4, "QK_MOUSE_BUTTON_4"}, + {QK_MOUSE_BUTTON_5, "QK_MOUSE_BUTTON_5"}, + {QK_MOUSE_BUTTON_6, "QK_MOUSE_BUTTON_6"}, + {QK_MOUSE_BUTTON_7, "QK_MOUSE_BUTTON_7"}, + {QK_MOUSE_BUTTON_8, "QK_MOUSE_BUTTON_8"}, + {QK_MOUSE_WHEEL_UP, "QK_MOUSE_WHEEL_UP"}, + {QK_MOUSE_WHEEL_DOWN, "QK_MOUSE_WHEEL_DOWN"}, + {QK_MOUSE_WHEEL_LEFT, "QK_MOUSE_WHEEL_LEFT"}, + {QK_MOUSE_WHEEL_RIGHT, "QK_MOUSE_WHEEL_RIGHT"}, + {QK_MOUSE_ACCELERATION_0, "QK_MOUSE_ACCELERATION_0"}, + {QK_MOUSE_ACCELERATION_1, "QK_MOUSE_ACCELERATION_1"}, + {QK_MOUSE_ACCELERATION_2, "QK_MOUSE_ACCELERATION_2"}, {KC_LEFT_CTRL, "KC_LEFT_CTRL"}, {KC_LEFT_SHIFT, "KC_LEFT_SHIFT"}, {KC_LEFT_ALT, "KC_LEFT_ALT"}, -- cgit v1.2.3 From 2477aa91617f51fc945b844c325455a2db90a55b Mon Sep 17 00:00:00 2001 From: Ryan Date: Sat, 6 Jul 2024 11:14:09 +1000 Subject: [docs] Update RGBLight (Underglow) keycode names (#23999) --- docs/features/encoders.md | 6 +++--- docs/features/rgblight.md | 48 ++++++++++++++++++++++++----------------------- docs/keycodes.md | 43 ++++++++++++++++++++++-------------------- 3 files changed, 51 insertions(+), 46 deletions(-) (limited to 'docs/features') diff --git a/docs/features/encoders.md b/docs/features/encoders.md index 73cbb4f3f3..a674eaa4a6 100644 --- a/docs/features/encoders.md +++ b/docs/features/encoders.md @@ -85,9 +85,9 @@ Your `keymap.c` will then need an encoder mapping defined (for four layers and t #if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { [0] = { ENCODER_CCW_CW(MS_WHLU, MS_WHLD), ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, - [1] = { ENCODER_CCW_CW(RGB_HUD, RGB_HUI), ENCODER_CCW_CW(RGB_SAD, RGB_SAI) }, - [2] = { ENCODER_CCW_CW(RGB_VAD, RGB_VAI), ENCODER_CCW_CW(RGB_SPD, RGB_SPI) }, - [3] = { ENCODER_CCW_CW(RGB_RMOD, RGB_MOD), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, + [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 ``` diff --git a/docs/features/rgblight.md b/docs/features/rgblight.md index ece1c10467..794398a0f9 100644 --- a/docs/features/rgblight.md +++ b/docs/features/rgblight.md @@ -59,30 +59,32 @@ Changing the **Value** sets the overall brightness.
## Keycodes -|Key |Aliases |Description | -|-------------------|----------|--------------------------------------------------------------------| -|`RGB_TOG` | |Toggle RGB lighting on or off | -|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | -|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | -|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | -|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | -|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | -|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | -|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held | -|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode | -|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode | -|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode | -|`RGB_MODE_SWIRL` |`RGB_M_SW`|Swirl animation mode | -|`RGB_MODE_SNAKE` |`RGB_M_SN`|Snake animation mode | -|`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode | -|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode | -|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | -|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode | -|`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode | +|Key |Aliases |Description | +|------------------------------|----------|---------------------------------------------------------------------| +|`QK_UNDERGLOW_TOGGLE` |`UG_TOGG` |Toggle RGB lighting on or off | +|`QK_UNDERGLOW_MODE_NEXT` |`UG_NEXT` |Cycle through modes, reverse direction when Shift is held | +|`QK_UNDERGLOW_MODE_PREVIOUS` |`UG_PREV` |Cycle through modes in reverse, forward direction when Shift is held | +|`QK_UNDERGLOW_HUE_UP` |`UG_HUEU` |Increase hue, decrease hue when Shift is held | +|`QK_UNDERGLOW_HUE_DOWN` |`UG_HUED` |Decrease hue, increase hue when Shift is held | +|`QK_UNDERGLOW_SATURATION_UP` |`UG_SATU` |Increase saturation, decrease saturation when Shift is held | +|`QK_UNDERGLOW_SATURATION_DOWN`|`UG_SATD` |Decrease saturation, increase saturation when Shift is held | +|`QK_UNDERGLOW_VALUE_UP` |`UG_VALU` |Increase value (brightness), decrease value when Shift is held | +|`QK_UNDERGLOW_VALUE_DOWN` |`UG_VALD` |Decrease value (brightness), increase value when Shift is held | +|`QK_UNDERGLOW_SPEED_UP` |`UG_SPDU` |Increase effect speed (brightness), decrease speed when Shift is held| +|`QK_UNDERGLOW_SPEED_DOWN` |`UG_SPDD` |Decrease effect speed (brightness), increase speed when Shift is held| +|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode (deprecated) | +|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode (deprecated) | +|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode (deprecated) | +|`RGB_MODE_SWIRL` |`RGB_M_SW`|Swirl animation mode (deprecated) | +|`RGB_MODE_SNAKE` |`RGB_M_SN`|Snake animation mode (deprecated) | +|`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode (deprecated) | +|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode (deprecated) | +|`RGB_MODE_GRADIENT` |`RGB_M_G` |Static gradient animation mode (deprecated) | +|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode (deprecated) | +|`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode (deprecated) | ::: tip -`RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUI)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. +These keycodes cannot be used with functions like `tap_code16()` as they are not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. ::: @@ -358,7 +360,7 @@ Lighting layers on split keyboards will require layer state synced to the slave ### Overriding RGB Lighting on/off status -Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`. +Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `UG_TOGG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`. ### Retain brightness diff --git a/docs/keycodes.md b/docs/keycodes.md index ea8b2e7b65..9038c2b6d7 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -704,26 +704,29 @@ See also: [Dynamic Tapping Term](tap_hold#dynamic-tapping-term) See also: [RGB Lighting](features/rgblight) -|Key |Aliases |Description | -|-------------------|----------|--------------------------------------------------------------------| -|`RGB_TOG` | |Toggle RGB lighting on or off | -|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | -|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | -|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | -|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | -|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | -|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | -|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held | -|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode | -|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode | -|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode | -|`RGB_MODE_SWIRL` |`RGB_M_SW`|Swirl animation mode | -|`RGB_MODE_SNAKE` |`RGB_M_SN`|Snake animation mode | -|`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode | -|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode | -|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | -|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red,Green,Blue test animation mode | +|Key |Aliases |Description | +|------------------------------|----------|---------------------------------------------------------------------| +|`QK_UNDERGLOW_TOGGLE` |`UG_TOGG` |Toggle RGB lighting on or off | +|`QK_UNDERGLOW_MODE_NEXT` |`UG_NEXT` |Cycle through modes, reverse direction when Shift is held | +|`QK_UNDERGLOW_MODE_PREVIOUS` |`UG_PREV` |Cycle through modes in reverse, forward direction when Shift is held | +|`QK_UNDERGLOW_HUE_UP` |`UG_HUEU` |Increase hue, decrease hue when Shift is held | +|`QK_UNDERGLOW_HUE_DOWN` |`UG_HUED` |Decrease hue, increase hue when Shift is held | +|`QK_UNDERGLOW_SATURATION_UP` |`UG_SATU` |Increase saturation, decrease saturation when Shift is held | +|`QK_UNDERGLOW_SATURATION_DOWN`|`UG_SATD` |Decrease saturation, increase saturation when Shift is held | +|`QK_UNDERGLOW_VALUE_UP` |`UG_VALU` |Increase value (brightness), decrease value when Shift is held | +|`QK_UNDERGLOW_VALUE_DOWN` |`UG_VALD` |Decrease value (brightness), increase value when Shift is held | +|`QK_UNDERGLOW_SPEED_UP` |`UG_SPDU` |Increase effect speed (brightness), decrease speed when Shift is held| +|`QK_UNDERGLOW_SPEED_DOWN` |`UG_SPDD` |Decrease effect speed (brightness), increase speed when Shift is held| +|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode (deprecated) | +|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode (deprecated) | +|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode (deprecated) | +|`RGB_MODE_SWIRL` |`RGB_M_SW`|Swirl animation mode (deprecated) | +|`RGB_MODE_SNAKE` |`RGB_M_SN`|Snake animation mode (deprecated) | +|`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode (deprecated) | +|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode (deprecated) | +|`RGB_MODE_GRADIENT` |`RGB_M_G` |Static gradient animation mode (deprecated) | +|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode (deprecated) | +|`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode (deprecated) | ## RGB Matrix Lighting {#rgb-matrix-lighting} -- cgit v1.2.3 From 85447bd53b15b0be387336169feae1c7ff87f15c Mon Sep 17 00:00:00 2001 From: Ryan Date: Mon, 15 Jul 2024 12:03:30 +1000 Subject: LED drivers: extract documentation from LED/RGB Matrix pages (#23630) --- docs/drivers/aw20216s.md | 133 +++++++++++ docs/drivers/is31fl3218.md | 194 +++++++++++++++ docs/drivers/is31fl3236.md | 228 ++++++++++++++++++ docs/drivers/is31fl3729.md | 300 ++++++++++++++++++++++++ docs/drivers/is31fl3731.md | 254 ++++++++++++++++++++ docs/drivers/is31fl3733.md | 338 +++++++++++++++++++++++++++ docs/drivers/is31fl3736.md | 322 +++++++++++++++++++++++++ docs/drivers/is31fl3737.md | 310 ++++++++++++++++++++++++ docs/drivers/is31fl3741.md | 310 ++++++++++++++++++++++++ docs/drivers/is31fl3742a.md | 310 ++++++++++++++++++++++++ docs/drivers/is31fl3743a.md | 320 +++++++++++++++++++++++++ docs/drivers/is31fl3745.md | 320 +++++++++++++++++++++++++ docs/drivers/is31fl3746a.md | 327 ++++++++++++++++++++++++++ docs/drivers/snled27351.md | 245 +++++++++++++++++++ docs/features/led_matrix.md | 188 ++------------- docs/features/rgb_matrix.md | 558 ++------------------------------------------ 16 files changed, 3958 insertions(+), 699 deletions(-) create mode 100644 docs/drivers/aw20216s.md create mode 100644 docs/drivers/is31fl3218.md create mode 100644 docs/drivers/is31fl3236.md create mode 100644 docs/drivers/is31fl3729.md create mode 100644 docs/drivers/is31fl3731.md create mode 100644 docs/drivers/is31fl3733.md create mode 100644 docs/drivers/is31fl3736.md create mode 100644 docs/drivers/is31fl3737.md create mode 100644 docs/drivers/is31fl3741.md create mode 100644 docs/drivers/is31fl3742a.md create mode 100644 docs/drivers/is31fl3743a.md create mode 100644 docs/drivers/is31fl3745.md create mode 100644 docs/drivers/is31fl3746a.md create mode 100644 docs/drivers/snled27351.md (limited to 'docs/features') diff --git a/docs/drivers/aw20216s.md b/docs/drivers/aw20216s.md new file mode 100644 index 0000000000..36a6d63c33 --- /dev/null +++ b/docs/drivers/aw20216s.md @@ -0,0 +1,133 @@ +# AW20216S Driver {#aw20216s-driver} + +SPI 18x12 LED matrix driver by Awinic. Supports a maximum of four drivers, each controlling up to 216 single-color LEDs, or 72 RGB LEDs. + +[AW20216S Datasheet](https://doc.awinic.com/doc/20230609wm/b6a9c70b-e1bd-495b-925f-bcbed3fc2620.pdf) + +## Usage {#usage} + +The AW20216S driver code is automatically included if you are using the [RGB Matrix](../features/rgb_matrix) feature with the `aw20216s` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led +SRC += aw20216s.c +SPI_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|-------------|-------------------------------------------------------------| +|`AW20216S_CS_PIN_1` |*Not defined*|The GPIO pin connected to the first driver's Chip Select pin | +|`AW20216S_CS_PIN_2` |*Not defined*|The GPIO pin connected to the second driver's Chip Select pin| +|`AW20216S_EN_PIN` |*Not defined*|The GPIO pin connected to the drivers' Enable pins | +|`AW20216S_SPI_MODE` |`0` |The SPI mode to use | +|`AW20216S_SPI_DIVISOR` |`4` |The SPI divisor to use | +|`AW20216S_SCALING_MAX` |`150` |The scaling value | +|`AW20216S_GLOBAL_CURRENT_MAX`|`150` |The global current control value | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. To adjust it, add the following to your `config.h`: + +```c +#define AW20216S_GLOBAL_CURRENT_MAX 150 +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure SPI](spi#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the first LED index on driver 0 has its red channel on `SW1_CS1`, green on `SW1_CS2` and blue on `SW1_CS3`. + +These values correspond to the matrix locations as shown in the datasheet on page 16, figure 16. + +## API {#api} + +### `struct aw20216s_led_t` {#api-aw20216s-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-aw20216s-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel. + - `uint8_t g` + The output PWM register address for the LED's green channel. + - `uint8_t b` + The output PWM register address for the LED's blue channel. + +--- + +### `void aw20216s_init(pin_t cs_pin)` {#api-aw20216s-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-aw20216s-init-arguments} + + - `pin_t cs_pin` + The GPIO connected to the Chip Select pin of the LED driver to initialize. + +--- + +### `void aw20216s_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-aw20216s-set-color} + +Set the color of a single LED. This function does not immediately update the LEDs; call `aw20216s_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-aw20216s-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_aw20216s_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void aw20216s_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-aw20216s-set-color-all} + +Set the color of all LEDs. + +#### Arguments {#api-aw20216s-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void aw20216s_update_pwm_buffers(pin_t cs_pin, uint8_t index)` {#api-aw20216s-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-aw20216s-update-pwm-buffers-arguments} + + - `pin_t cs_pin` + The GPIO connected to the Chip Select pin of the driver. + - `uint8_t index` + The index of the driver. diff --git a/docs/drivers/is31fl3218.md b/docs/drivers/is31fl3218.md new file mode 100644 index 0000000000..1c98069120 --- /dev/null +++ b/docs/drivers/is31fl3218.md @@ -0,0 +1,194 @@ +# IS31FL3218 Driver {#is31fl3218-driver} + +I²C LED driver by Lumissil. Supports up to 18 single-color LEDs, or 6 RGB LEDs. + +[IS31FL3218 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3218_DS.pdf) + +## Usage {#usage} + +The IS31FL3218 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3218` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3218-mono.c # For single-color +SRC += is31fl3218.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|---------------------------------------------------| +|`IS31FL3218_SDB_PIN` |*Not defined*|The GPIO pin connected to the driver's shutdown pin| +|`IS31FL3218_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3218_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3218's 7-bit I²C address is `0x54`, available as `IS31FL3218_I2C_ADDRESS`. + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { +/* R G B */ + {OUT1, OUT2, OUT3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index all have their anodes connected to `VCC`, and their cathodes on the `OUT1`, `OUT2` and `OUT3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { +/* V */ + {OUT1}, + // etc... +}; +``` + +## API {#api} + +### `struct is31fl3218_led_t` {#api-is31fl3218-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3218-led-t-members} + + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3218_init(void)` {#api-is31fl3218-init} + +Initialize the LED driver. This function should be called first. + +--- + +### `void is31fl3218_write_register(uint8_t reg, uint8_t data)` {#api-is31fl3218-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3218-write-register-arguments} + + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3218_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3218-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3218_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3218-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3218_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3218-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3218-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3218_set_value(int index, uint8_t value)` {#api-is31fl3218-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3218_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3218-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3218_set_value_all(uint8_t value)` {#api-is31fl3218-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3218-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3218_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3218-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3218_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3218-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3218_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3218-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3218_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3218-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3218_update_pwm_buffers(void)` {#api-is31fl3218-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +--- + +### `void is31fl3218_update_led_control_registers(void)` {#api-is31fl3218-update-led-control-registers} + +Flush the LED control register values to the LED driver. diff --git a/docs/drivers/is31fl3236.md b/docs/drivers/is31fl3236.md new file mode 100644 index 0000000000..98e05e4abd --- /dev/null +++ b/docs/drivers/is31fl3236.md @@ -0,0 +1,228 @@ +# IS31FL3236 Driver {#is31fl3236-driver} + +I²C LED driver by Lumissil. Supports a maximum of four drivers, each controlling up to 36 single-color LEDs, or 12 RGB LEDs. + +[IS31FL3236 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3236_DS.pdf) + +## Usage {#usage} + +The IS31FL3236 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3236` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3236-mono.c # For single-color +SRC += is31fl3236.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`IS31FL3236_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3236_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3236_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3236_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`IS31FL3236_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`IS31FL3236_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`IS31FL3236_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3236 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. + +To configure this, set the `IS31FL3236_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3236_I2C_ADDRESS_GND`|`0x3C`| +|`IS31FL3236_I2C_ADDRESS_SCL`|`0x3D`| +|`IS31FL3236_I2C_ADDRESS_SDA`|`0x3E`| +|`IS31FL3236_I2C_ADDRESS_VCC`|`0x3F`| + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { +/* Driver + | R G B */ + {0, OUT1, OUT2, OUT3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to `VCC`, and their cathodes on the `OUT1`, `OUT2` and `OUT3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { +/* Driver + | V */ + {0, OUT1}, + // etc... +}; +``` + +## API {#api} + +### `struct is31fl3236_led_t` {#api-is31fl3236-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3236-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3236_init(uint8_t index)` {#api-is31fl3236-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3236-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3236_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3236-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3236-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3236_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3236-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3236_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3236-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3236_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3236-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3236-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3236_set_value(int index, uint8_t value)` {#api-is31fl3236-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3236_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3236-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3236_set_value_all(uint8_t value)` {#api-is31fl3236-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3236-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3236_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3236-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3236_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3236-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3236_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3236-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3236_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3236-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3236_update_pwm_buffers(uint8_t index)` {#api-is31fl3236-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3236-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3236_update_led_control_registers(uint8_t index)` {#api-is31fl3236-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3236-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3729.md b/docs/drivers/is31fl3729.md new file mode 100644 index 0000000000..32618d82d5 --- /dev/null +++ b/docs/drivers/is31fl3729.md @@ -0,0 +1,300 @@ +# IS31FL3729 Driver {#is31fl3729-driver} + +I²C 16x8/15x9 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 135 single-color LEDs, or 45 RGB LEDs. + +[IS31FL3729 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3729_DS.pdf) + +## Usage {#usage} + +The IS31FL3729 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3729` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3729-mono.c # For single-color +SRC += is31fl3729.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|--------------------------------------|----------------------------------------------------| +|`IS31FL3729_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3729_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3729_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3729_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3729_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3729_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3729_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3729_PWM_FREQUENCY` |`IS31FL3729_PWM_FREQUENCY_32K_HZ` |The PWM frequency of the LEDs | +|`IS31FL3729_SW_PULLDOWN` |`IS31FL3729_SW_PULLDOWN_2K_OHM_SW_OFF`|The `SWx` pullup resistor value | +|`IS31FL3729_CS_PULLUP` |`IS31FL3729_CS_PULLUP_2K_OHM_CS_OFF` |The `CSx` pulldown resistor value | +|`IS31FL3729_GLOBAL_CURRENT` |`0x40` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3729 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. + +To configure this, set the `IS31FL3729_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3729_I2C_ADDRESS_GND`|`0x34`| +|`IS31FL3729_I2C_ADDRESS_SCL`|`0x35`| +|`IS31FL3729_I2C_ADDRESS_SDA`|`0x36`| +|`IS31FL3729_I2C_ADDRESS_VCC`|`0x37`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted by adding the following to your `config.h`: + +```c +#define IS31FL3729_PWM_FREQUENCY IS31FL3729_PWM_FREQUENCY_32K_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|----------------| +|`IS31FL3729_PWM_FREQUENCY_55K_HZ` |55 kHz | +|`IS31FL3729_PWM_FREQUENCY_32K_HZ` |32 kHz (default)| +|`IS31FL3729_PWM_FREQUENCY_4K_HZ` |4 kHz | +|`IS31FL3729_PWM_FREQUENCY_2K_HZ` |2 kHz | +|`IS31FL3729_PWM_FREQUENCY_1K_HZ` |1 kHz | +|`IS31FL3729_PWM_FREQUENCY_500_HZ` |500 Hz | +|`IS31FL3729_PWM_FREQUENCY_250_HZ` |250 Hz | +|`IS31FL3729_PWM_FREQUENCY_80K_HZ` |80 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 18) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3729_SW_PULLDOWN IS31FL3729_SW_PULLDOWN_2K_OHM_SW_OFF +#define IS31FL3729_CS_PULLUP IS31FL3729_CS_PULLUP_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3729_SW_PULLDOWN` are: + +|Define |Resistance | +|---------------------------------------|------------------------------| +|`IS31FL3729_SW_PULLDOWN_0_OHM` |None | +|`IS31FL3729_SW_PULLDOWN_0K5_OHM_SW_OFF`|0.5 kΩ in SWy off time | +|`IS31FL3729_SW_PULLDOWN_1K_OHM_SW_OFF` |1 kΩ in SWy off time | +|`IS31FL3729_SW_PULLDOWN_2K_OHM_SW_OFF` |2 kΩ in SWy off time (default)| +|`IS31FL3729_SW_PULLDOWN_1K_OHM` |1 kΩ | +|`IS31FL3729_SW_PULLDOWN_2K_OHM` |2 kΩ | +|`IS31FL3729_SW_PULLDOWN_4K_OHM` |4 kΩ | +|`IS31FL3729_SW_PULLDOWN_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3729_CS_PULLUP` are: + +|Define |Resistance | +|-------------------------------------|------------------------------| +|`IS31FL3729_CS_PULLUP_0_OHM` |None | +|`IS31FL3729_CS_PULLUP_0K5_OHM_CS_OFF`|0.5 kΩ in CSx off time | +|`IS31FL3729_CS_PULLUP_1K_OHM_CS_OFF` |1 kΩ in CSx off time | +|`IS31FL3729_CS_PULLUP_2K_OHM_CS_OFF` |2 kΩ in CSx off time (default)| +|`IS31FL3729_CS_PULLUP_1K_OHM` |1 kΩ | +|`IS31FL3729_CS_PULLUP_2K_OHM` |2 kΩ | +|`IS31FL3729_CS_PULLUP_4K_OHM` |4 kΩ | +|`IS31FL3729_CS_PULLUP_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is 64, but if you need to adjust it, add the following to your `config.h`: + +```c +#define IS31FL3729_GLOBAL_CURRENT 0x40 +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3729_led_t PROGMEM g_is31fl3729_leds[IS31FL3729_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3729_led_t PROGMEM g_is31fl3729_leds[IS31FL3729_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 9. + +## API {#api} + +### `struct is31fl3729_led_t` {#api-is31fl3729-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3729-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3729_init(uint8_t index)` {#api-is31fl3729-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3729-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3729_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3729-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3729-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3729_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3729-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3729_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3729_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3729-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3729-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3729_set_value(int index, uint8_t value)` {#api-is31fl3729-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3729_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3729_set_value_all(uint8_t value)` {#api-is31fl3729-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3729-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3729_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3729-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3729_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3729_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3729-set-scaling-register-mono} + +Configure the scaling registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3729_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3729_update_pwm_buffers(uint8_t index)` {#api-is31fl3729-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3729-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3729_update_scaling_registers(uint8_t index)` {#api-is31fl3729-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3729-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3731.md b/docs/drivers/is31fl3731.md new file mode 100644 index 0000000000..0d928a919e --- /dev/null +++ b/docs/drivers/is31fl3731.md @@ -0,0 +1,254 @@ +# IS31FL3731 Driver {#is31fl3731-driver} + +I²C Charlieplexed 16x9 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 144 single-color LEDs, or 48 RGB LEDs. + +[IS31FL3731 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3731_DS.pdf) + +## Usage {#usage} + +The IS31FL3731 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3731` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3731-mono.c # For single-color +SRC += is31fl3731.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`IS31FL3731_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3731_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3731_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3731_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`IS31FL3731_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`IS31FL3731_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`IS31FL3731_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | +|`IS31FL3731_DEGHOST` |*Not defined*|Enable ghost image prevention | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3731 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. + +To configure this, set the `IS31FL3731_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3731_I2C_ADDRESS_GND`|`0x74`| +|`IS31FL3731_I2C_ADDRESS_SCL`|`0x75`| +|`IS31FL3731_I2C_ADDRESS_SDA`|`0x76`| +|`IS31FL3731_I2C_ADDRESS_VCC`|`0x77`| + +### De-Ghosting {#de-ghosting} + +This setting enables the de-ghosting feature on the IS31FL3731. See this [Application Note](https://www.lumissil.com/assets/pdf/core/IS31FL3731_AN.pdf) (p. 15) for more information. + +To enable, add the following to your `config.h`: + +```c +#define IS31FL3731_DEGHOST +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { +/* Driver + * | R G B */ + {0, C1_1, C1_2, C1_3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `CA1` pin, and their anodes on the `CA2`, `CA3` and `CA4` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { +/* Driver + * | V */ + {0, C1_1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 11, figure 8. + +## API {#api} + +### `struct is31fl3731_led_t` {#api-is31fl3731-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3731-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3731_init(uint8_t index)` {#api-is31fl3731-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3731-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3731_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3731-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3731-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3731_select_page(uint8_t index, uint8_t page)` {#api-is31fl3731-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3731-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3731_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3731_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3731-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3731_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3731-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3731_set_value(int index, uint8_t value)` {#api-is31fl3731-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3731_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3731-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3731_set_value_all(uint8_t value)` {#api-is31fl3731-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3731-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3731_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3731-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3731_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3731-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3731_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3731-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3731_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3731-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3731_update_pwm_buffers(uint8_t index)` {#api-is31fl3731-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3731-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3731_update_led_control_registers(uint8_t index)` {#api-is31fl3731-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3731-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3733.md b/docs/drivers/is31fl3733.md new file mode 100644 index 0000000000..e299f785bd --- /dev/null +++ b/docs/drivers/is31fl3733.md @@ -0,0 +1,338 @@ +# IS31FL3733 Driver {#is31fl3733-driver} + +I²C 12x16 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 192 single-color LEDs, or 64 RGB LEDs. + +[IS31FL3733 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3733_DS.pdf) + +## Usage {#usage} + +The IS31FL3733 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3733` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3733-mono.c # For single-color +SRC += is31fl3733.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3733_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3733_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3733_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3733_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3733_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3733_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3733_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3733_SYNC_1` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 0 | +|`IS31FL3733_SYNC_2` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 1 | +|`IS31FL3733_SYNC_3` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 2 | +|`IS31FL3733_SYNC_4` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 3 | +|`IS31FL3733_PWM_FREQUENCY` |`IS31FL3733_PWM_FREQUENCY_8K4_HZ`|The PWM frequency of the LEDs (IS31FL3733B only) | +|`IS31FL3733_SW_PULLUP` |`IS31FL3733_PUR_0_OHM` |The `SWx` pullup resistor value | +|`IS31FL3733_CS_PULLDOWN` |`IS31FL3733_PDR_0_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3733_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3733 has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3733_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|--------------------------------|------| +|`IS31FL3733_I2C_ADDRESS_GND_GND`|`0x50`| +|`IS31FL3733_I2C_ADDRESS_GND_SCL`|`0x51`| +|`IS31FL3733_I2C_ADDRESS_GND_SDA`|`0x52`| +|`IS31FL3733_I2C_ADDRESS_GND_VCC`|`0x53`| +|`IS31FL3733_I2C_ADDRESS_SCL_GND`|`0x54`| +|`IS31FL3733_I2C_ADDRESS_SCL_SCL`|`0x55`| +|`IS31FL3733_I2C_ADDRESS_SCL_SDA`|`0x56`| +|`IS31FL3733_I2C_ADDRESS_SCL_VCC`|`0x57`| +|`IS31FL3733_I2C_ADDRESS_SDA_GND`|`0x58`| +|`IS31FL3733_I2C_ADDRESS_SDA_SCL`|`0x59`| +|`IS31FL3733_I2C_ADDRESS_SDA_SDA`|`0x5A`| +|`IS31FL3733_I2C_ADDRESS_SDA_VCC`|`0x5B`| +|`IS31FL3733_I2C_ADDRESS_VCC_GND`|`0x5C`| +|`IS31FL3733_I2C_ADDRESS_VCC_SCL`|`0x5D`| +|`IS31FL3733_I2C_ADDRESS_VCC_SDA`|`0x5E`| +|`IS31FL3733_I2C_ADDRESS_VCC_VCC`|`0x5F`| + +### Multi-Driver Synchronization {#multi-driver-synchronization} + +Multiple IS31FL3733 drivers can be synchronized by connecting the `SYNC` pins together. One driver must be designated as the "master", and the others configured as "slave". + +To do this, set the `IS31FL3733_SYNC_n` defines accordingly in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------|---------------------------| +|`IS31FL3733_SYNC_NONE` |No synchronization | +|`IS31FL3733_SYNC_MASTER`|Driver configured as master| +|`IS31FL3733_SYNC_SLAVE` |Driver configured as slave | + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3733B only) by adding the following to your `config.h`: + +```c +#define IS31FL3733_PWM_FREQUENCY IS31FL3733_PWM_FREQUENCY_8K4_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|-----------------| +|`IS31FL3733_PWM_FREQUENCY_8K4_HZ` |8.4 kHz (default)| +|`IS31FL3733_PWM_FREQUENCY_4K2_HZ` |4.2 kHz | +|`IS31FL3733_PWM_FREQUENCY_26K7_HZ`|26.7 kHz | +|`IS31FL3733_PWM_FREQUENCY_2K1_HZ` |2.1 kHz | +|`IS31FL3733_PWM_FREQUENCY_1K05_HZ`|1.05 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3733_SW_PULLUP IS31FL3733_PUR_0_OHM +#define IS31FL3733_CS_PULLDOWN IS31FL3733_PUR_0_OHM +``` + +Valid values for `IS31FL3733_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3733_PUR_0_OHM` |None (default)| +|`IS31FL3733_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3733_PUR_1K_OHM` |1 kΩ | +|`IS31FL3733_PUR_2K_OHM` |2 kΩ | +|`IS31FL3733_PUR_4K_OHM` |4 kΩ | +|`IS31FL3733_PUR_8K_OHM` |8 kΩ | +|`IS31FL3733_PUR_16K_OHM`|16 kΩ | +|`IS31FL3733_PUR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3733_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3733_PDR_0_OHM` |None (default)| +|`IS31FL3733_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3733_PDR_1K_OHM` |1 kΩ | +|`IS31FL3733_PDR_2K_OHM` |2 kΩ | +|`IS31FL3733_PDR_4K_OHM` |4 kΩ | +|`IS31FL3733_PDR_8K_OHM` |8 kΩ | +|`IS31FL3733_PDR_16K_OHM`|16 kΩ | +|`IS31FL3733_PDR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3733_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `SW1` pin, and their anodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 15, figure 9. + +## API {#api} + +### `struct is31fl3733_led_t` {#api-is31fl3733-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3733-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3733_init(uint8_t index)` {#api-is31fl3733-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3733-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3733_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3733-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3733-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3733_select_page(uint8_t index, uint8_t page)` {#api-is31fl3733-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3733-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3733_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3733-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3733_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3733_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3733-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3733-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3733_set_value(int index, uint8_t value)` {#api-is31fl3733-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3733_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3733_set_value_all(uint8_t value)` {#api-is31fl3733-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3733-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3733_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3733-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3733_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3733_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3733-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3733_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3733_update_pwm_buffers(uint8_t index)` {#api-is31fl3733-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3733-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3733_update_led_control_registers(uint8_t index)` {#api-is31fl3733-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3733-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3736.md b/docs/drivers/is31fl3736.md new file mode 100644 index 0000000000..b679a232cd --- /dev/null +++ b/docs/drivers/is31fl3736.md @@ -0,0 +1,322 @@ +# IS31FL3736 Driver {#is31fl3736-driver} + +I²C 12x8 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 96 single-color LEDs, or 32 RGB LEDs. + +[IS31FL3736 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3736_DS.pdf) + +## Usage {#usage} + +The IS31FL3736 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3736` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3736-mono.c # For single-color +SRC += is31fl3736.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3736_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3736_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3736_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3736_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3736_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3736_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3736_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3736_PWM_FREQUENCY` |`IS31FL3736_PWM_FREQUENCY_8K4_HZ`|The PWM frequency of the LEDs (IS31FL3736B only) | +|`IS31FL3736_SW_PULLUP` |`IS31FL3736_PUR_0_OHM` |The `SWx` pullup resistor value | +|`IS31FL3736_CS_PULLDOWN` |`IS31FL3736_PDR_0_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3736_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3736 has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3736_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|--------------------------------|------| +|`IS31FL3736_I2C_ADDRESS_GND_GND`|`0x50`| +|`IS31FL3736_I2C_ADDRESS_GND_SCL`|`0x51`| +|`IS31FL3736_I2C_ADDRESS_GND_SDA`|`0x52`| +|`IS31FL3736_I2C_ADDRESS_GND_VCC`|`0x53`| +|`IS31FL3736_I2C_ADDRESS_SCL_GND`|`0x54`| +|`IS31FL3736_I2C_ADDRESS_SCL_SCL`|`0x55`| +|`IS31FL3736_I2C_ADDRESS_SCL_SDA`|`0x56`| +|`IS31FL3736_I2C_ADDRESS_SCL_VCC`|`0x57`| +|`IS31FL3736_I2C_ADDRESS_SDA_GND`|`0x58`| +|`IS31FL3736_I2C_ADDRESS_SDA_SCL`|`0x59`| +|`IS31FL3736_I2C_ADDRESS_SDA_SDA`|`0x5A`| +|`IS31FL3736_I2C_ADDRESS_SDA_VCC`|`0x5B`| +|`IS31FL3736_I2C_ADDRESS_VCC_GND`|`0x5C`| +|`IS31FL3736_I2C_ADDRESS_VCC_SCL`|`0x5D`| +|`IS31FL3736_I2C_ADDRESS_VCC_SDA`|`0x5E`| +|`IS31FL3736_I2C_ADDRESS_VCC_VCC`|`0x5F`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3736B only) by adding the following to your `config.h`: + +```c +#define IS31FL3736_PWM_FREQUENCY IS31FL3736_PWM_FREQUENCY_8K4_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|-----------------| +|`IS31FL3736_PWM_FREQUENCY_8K4_HZ` |8.4 kHz (default)| +|`IS31FL3736_PWM_FREQUENCY_4K2_HZ` |4.2 kHz | +|`IS31FL3736_PWM_FREQUENCY_26K7_HZ`|26.7 kHz | +|`IS31FL3736_PWM_FREQUENCY_2K1_HZ` |2.1 kHz | +|`IS31FL3736_PWM_FREQUENCY_1K05_HZ`|1.05 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 25) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3736_SW_PULLUP IS31FL3736_PUR_0_OHM +#define IS31FL3736_CS_PULLDOWN IS31FL3736_PDR_0_OHM +``` + +Valid values for `IS31FL3736_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3736_PUR_0_OHM` |None (default)| +|`IS31FL3736_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3736_PUR_1K_OHM` |1 kΩ | +|`IS31FL3736_PUR_2K_OHM` |2 kΩ | +|`IS31FL3736_PUR_4K_OHM` |4 kΩ | +|`IS31FL3736_PUR_8K_OHM` |8 kΩ | +|`IS31FL3736_PUR_16K_OHM`|16 kΩ | +|`IS31FL3736_PUR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3736_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3736_PDR_0_OHM` |None (default)| +|`IS31FL3736_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3736_PDR_1K_OHM` |1 kΩ | +|`IS31FL3736_PDR_2K_OHM` |2 kΩ | +|`IS31FL3736_PDR_4K_OHM` |4 kΩ | +|`IS31FL3736_PDR_8K_OHM` |8 kΩ | +|`IS31FL3736_PDR_16K_OHM`|16 kΩ | +|`IS31FL3736_PDR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3736_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `SW1` pin, and their anodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 16, figure 9. + +## API {#api} + +### `struct is31fl3736_led_t` {#api-is31fl3736-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3736-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3736_init(uint8_t index)` {#api-is31fl3736-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3736-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3736_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3736-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3736-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3736_select_page(uint8_t index, uint8_t page)` {#api-is31fl3736-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3736-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3736_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3736-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3736_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3736_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3736-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3736-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3736_set_value(int index, uint8_t value)` {#api-is31fl3736-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3736_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3736_set_value_all(uint8_t value)` {#api-is31fl3736-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3736-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3736_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3736-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3736_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3736_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3736-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3736_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3736_update_pwm_buffers(uint8_t index)` {#api-is31fl3736-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3736-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3736_update_led_control_registers(uint8_t index)` {#api-is31fl3736-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3736-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3737.md b/docs/drivers/is31fl3737.md new file mode 100644 index 0000000000..d23def237f --- /dev/null +++ b/docs/drivers/is31fl3737.md @@ -0,0 +1,310 @@ +# IS31FL3737 Driver {#is31fl3737-driver} + +I²C 12x12 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 144 single-color LEDs, or 48 RGB LEDs. + +[IS31FL3737 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3737_DS.pdf) + +## Usage {#usage} + +The IS31FL3737 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3737` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3737-mono.c # For single-color +SRC += is31fl3737.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3737_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3737_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3737_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3737_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3737_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3737_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3737_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3737_PWM_FREQUENCY` |`IS31FL3737_PWM_FREQUENCY_8K4_HZ`|The PWM frequency of the LEDs (IS31FL3737B only) | +|`IS31FL3737_SW_PULLUP` |`IS31FL3737_PUR_0_OHM` |The `SWx` pullup resistor value | +|`IS31FL3737_CS_PULLDOWN` |`IS31FL3737_PDR_0_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3737_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3737 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `IS31FL3737_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3737_I2C_ADDRESS_GND`|`0x50`| +|`IS31FL3737_I2C_ADDRESS_SCL`|`0x55`| +|`IS31FL3737_I2C_ADDRESS_SDA`|`0x5A`| +|`IS31FL3737_I2C_ADDRESS_VCC`|`0x5F`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3737B only) by adding the following to your `config.h`: + +```c +#define IS31FL3737_PWM_FREQUENCY IS31FL3737_PWM_FREQUENCY_8K4_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|-----------------| +|`IS31FL3737_PWM_FREQUENCY_8K4_HZ` |8.4 kHz (default)| +|`IS31FL3737_PWM_FREQUENCY_4K2_HZ` |4.2 kHz | +|`IS31FL3737_PWM_FREQUENCY_26K7_HZ`|26.7 kHz | +|`IS31FL3737_PWM_FREQUENCY_2K1_HZ` |2.1 kHz | +|`IS31FL3737_PWM_FREQUENCY_1K05_HZ`|1.05 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3737_SW_PULLUP IS31FL3737_PUR_0_OHM +#define IS31FL3737_CS_PULLDOWN IS31FL3737_PDR_0_OHM +``` + +Valid values for `IS31FL3737_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3737_PUR_0_OHM` |None (default)| +|`IS31FL3737_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3737_PUR_1K_OHM` |1 kΩ | +|`IS31FL3737_PUR_2K_OHM` |2 kΩ | +|`IS31FL3737_PUR_4K_OHM` |4 kΩ | +|`IS31FL3737_PUR_8K_OHM` |8 kΩ | +|`IS31FL3737_PUR_16K_OHM`|16 kΩ | +|`IS31FL3737_PUR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3737_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3737_PDR_0_OHM` |None (default)| +|`IS31FL3737_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3737_PDR_1K_OHM` |1 kΩ | +|`IS31FL3737_PDR_2K_OHM` |2 kΩ | +|`IS31FL3737_PDR_4K_OHM` |4 kΩ | +|`IS31FL3737_PDR_8K_OHM` |8 kΩ | +|`IS31FL3737_PDR_16K_OHM`|16 kΩ | +|`IS31FL3737_PDR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3737_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `SW1` pin, and their anodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 15, figure 9. + +## API {#api} + +### `struct is31fl3737_led_t` {#api-is31fl3737-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3737-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3737_init(uint8_t index)` {#api-is31fl3737-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3737-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3737_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3737-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3737-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3737_select_page(uint8_t index, uint8_t page)` {#api-is31fl3737-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3737-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3737_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3737-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3737_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3737_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3737-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3737-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3737_set_value(int index, uint8_t value)` {#api-is31fl3737-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3737_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3737_set_value_all(uint8_t value)` {#api-is31fl3737-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3737-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3737_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3737-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3737_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3737_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3737-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3737_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3737_update_pwm_buffers(uint8_t index)` {#api-is31fl3737-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3737-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3737_update_led_control_registers(uint8_t index)` {#api-is31fl3737-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3737-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3741.md b/docs/drivers/is31fl3741.md new file mode 100644 index 0000000000..dce5c08b21 --- /dev/null +++ b/docs/drivers/is31fl3741.md @@ -0,0 +1,310 @@ +# IS31FL3741 Driver {#is31fl3741-driver} + +I²C 39x9 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 351 single-color LEDs, or 117 RGB LEDs. + +[IS31FL3741A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3741A_DS.pdf) + +## Usage {#usage} + +The IS31FL3741 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3741` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3741-mono.c # For single-color +SRC += is31fl3741.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3741_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3741_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3741_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3741_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3741_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3741_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3741_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3741_CONFIGURATION` |`1` |The value of the configuration register | +|`IS31FL3741_PWM_FREQUENCY` |`IS31FL3741_PWM_FREQUENCY_29K_HZ`|The PWM frequency of the LEDs (IS31FL3741A only) | +|`IS31FL3741_SW_PULLUP` |`IS31FL3741_PUR_32K_OHM` |The `SWx` pullup resistor value | +|`IS31FL3741_CS_PULLDOWN` |`IS31FL3741_PDR_32K_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3741_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3741 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `IS31FL3741_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3741_I2C_ADDRESS_GND`|`0x30`| +|`IS31FL3741_I2C_ADDRESS_SCL`|`0x31`| +|`IS31FL3741_I2C_ADDRESS_SDA`|`0x32`| +|`IS31FL3741_I2C_ADDRESS_VCC`|`0x33`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3741A only) by adding the following to your `config.h`: + +```c +#define IS31FL3741_PWM_FREQUENCY IS31FL3741_PWM_FREQUENCY_29K_HZ +``` + +Valid values are: + +|Define |Frequency | +|---------------------------------|----------------| +|`IS31FL3741_PWM_FREQUENCY_29K_HZ`|29 kHz (default)| +|`IS31FL3741_PWM_FREQUENCY_3K6_HZ`|3.6 kHz | +|`IS31FL3741_PWM_FREQUENCY_1K8_HZ`|1.8 kHz | +|`IS31FL3741_PWM_FREQUENCY_900_HZ`|900 Hz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `CSx` and `SWy` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 18) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3741_SW_PULLUP IS31FL3741_PUR_32K_OHM +#define IS31FL3741_CS_PULLDOWN IS31FL3741_PDR_32K_OHM +``` + +Valid values for `IS31FL3741_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|---------------| +|`IS31FL3741_PUR_0_OHM` |None | +|`IS31FL3741_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3741_PUR_1K_OHM` |1 kΩ | +|`IS31FL3741_PUR_2K_OHM` |2 kΩ | +|`IS31FL3741_PUR_4K_OHM` |4 kΩ | +|`IS31FL3741_PUR_8K_OHM` |8 kΩ | +|`IS31FL3741_PUR_16K_OHM`|16 kΩ | +|`IS31FL3741_PUR_32K_OHM`|32 kΩ (default)| + +Valid values for `IS31FL3741_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|---------------| +|`IS31FL3741_PDR_0_OHM` |None | +|`IS31FL3741_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3741_PDR_1K_OHM` |1 kΩ | +|`IS31FL3741_PDR_2K_OHM` |2 kΩ | +|`IS31FL3741_PDR_4K_OHM` |4 kΩ | +|`IS31FL3741_PDR_8K_OHM` |8 kΩ | +|`IS31FL3741_PDR_16K_OHM`|16 kΩ | +|`IS31FL3741_PDR_32K_OHM`|32 kΩ (default)| + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3741_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3741_led_t PROGMEM g_is31fl3741_leds[IS31FL3741_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3741_led_t PROGMEM g_is31fl3741_leds[IS31FL3741_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 8. + +## API {#api} + +### `struct is31fl3741_led_t` {#api-is31fl3741-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3741-led-t-members} + + - `uint32_t driver` + The driver index of the LED, from 0 to 3. + - `uint32_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint32_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint32_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint32_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3741_init(uint8_t index)` {#api-is31fl3741-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3741-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3741_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3741-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3741-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3741_select_page(uint8_t index, uint8_t page)` {#api-is31fl3741-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3741-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3741_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3741-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3741_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3741_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3741-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3741-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3741_set_value(int index, uint8_t value)` {#api-is31fl3741-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3741_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3741_set_value_all(uint8_t value)` {#api-is31fl3741-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3741-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3741_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3741-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3741_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3741_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3741-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3741_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3741_update_pwm_buffers(uint8_t index)` {#api-is31fl3741-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3741-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3741_update_led_control_registers(uint8_t index)` {#api-is31fl3741-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3741-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3742a.md b/docs/drivers/is31fl3742a.md new file mode 100644 index 0000000000..ebe648cba4 --- /dev/null +++ b/docs/drivers/is31fl3742a.md @@ -0,0 +1,310 @@ +# IS31FL3742A Driver {#is31fl3742a-driver} + +I²C 30x6 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 180 single-color LEDs, or 60 RGB LEDs. + +[IS31FL3742A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) + +## Usage {#usage} + +The IS31FL3742A driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3742a` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3742a-mono.c # For single-color +SRC += is31fl3742a.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|----------------------------------|----------------------------------------------------| +|`IS31FL3742A_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3742A_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3742A_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3742A_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3742A_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3742A_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3742A_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3742A_CONFIGURATION` |`0x31` |The value of the configuration register | +|`IS31FL3742A_PWM_FREQUENCY` |`IS31FL3742A_PWM_FREQUENCY_29K_HZ`|The PWM frequency of the LEDs | +|`IS31FL3742A_SW_PULLDOWN` |`IS31FL3742A_PDR_8K_OHM` |The `SWx` pulldown resistor value | +|`IS31FL3742A_CS_PULLUP` |`IS31FL3742A_PUR_8K_OHM` |The `CSx` pullup resistor value | +|`IS31FL3742A_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3742A has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `IS31FL3742A_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|-----------------------------|------| +|`IS31FL3742A_I2C_ADDRESS_GND`|`0x30`| +|`IS31FL3742A_I2C_ADDRESS_SCL`|`0x31`| +|`IS31FL3742A_I2C_ADDRESS_SDA`|`0x32`| +|`IS31FL3742A_I2C_ADDRESS_VCC`|`0x33`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted by adding the following to your `config.h`: + +```c +#define IS31FL3742A_PWM_FREQUENCY IS31FL3742A_PWM_FREQUENCY_29K_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|----------------| +|`IS31FL3742A_PWM_FREQUENCY_29K_HZ`|29 kHz (default)| +|`IS31FL3742A_PWM_FREQUENCY_3K6_HZ`|3.6 kHz | +|`IS31FL3742A_PWM_FREQUENCY_1K8_HZ`|1.8 kHz | +|`IS31FL3742A_PWM_FREQUENCY_900_HZ`|900 Hz | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3742A_SW_PULLDOWN IS31FL3742A_PDR_8K_OHM +#define IS31FL3742A_CS_PULLUP IS31FL3742A_PUR_8K_OHM +``` + +Valid values for `IS31FL3742A_SW_PULLDOWN` are: + +|Define |Resistance | +|-------------------------|--------------| +|`IS31FL3742A_PDR_0_OHM` |None | +|`IS31FL3742A_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3742A_PDR_1K_OHM` |1 kΩ | +|`IS31FL3742A_PDR_2K_OHM` |2 kΩ | +|`IS31FL3742A_PDR_4K_OHM` |4 kΩ | +|`IS31FL3742A_PDR_8K_OHM` |8 kΩ (default)| +|`IS31FL3742A_PDR_16K_OHM`|16 kΩ | +|`IS31FL3742A_PDR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3742A_CS_PULLUP` are: + +|Define |Resistance | +|-------------------------|--------------| +|`IS31FL3742A_PUR_0_OHM` |None | +|`IS31FL3742A_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3742A_PUR_1K_OHM` |1 kΩ | +|`IS31FL3742A_PUR_2K_OHM` |2 kΩ | +|`IS31FL3742A_PUR_4K_OHM` |4 kΩ | +|`IS31FL3742A_PUR_8K_OHM` |8 kΩ (default)| +|`IS31FL3742A_PUR_16K_OHM`|16 kΩ | +|`IS31FL3742A_PUR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3742A_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3742a_led_t PROGMEM g_is31fl3742a_leds[IS31FL3742A_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3742a_led_t PROGMEM g_is31fl3742a_leds[IS31FL3742A_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 8. + +## API {#api} + +### `struct is31fl3742a_led_t` {#api-is31fl3742a-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3742a-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3742a_init(uint8_t index)` {#api-is31fl3742a-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3742a-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3742a_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3742a-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3742a-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3742a_select_page(uint8_t index, uint8_t page)` {#api-is31fl3742a-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3742a-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3742a_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3742a-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3742a_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3742a-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3742a-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3742a_set_value(int index, uint8_t value)` {#api-is31fl3742a-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3742a_set_value_all(uint8_t value)` {#api-is31fl3742a-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3742a-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3742a_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3742a-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3742a_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3742a-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3742a_update_pwm_buffers(uint8_t index)` {#api-is31fl3742a-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3742a-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3742a_update_scaling_registers(uint8_t index)` {#api-is31fl3742a-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3742a-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3743a.md b/docs/drivers/is31fl3743a.md new file mode 100644 index 0000000000..9ca55c5eeb --- /dev/null +++ b/docs/drivers/is31fl3743a.md @@ -0,0 +1,320 @@ +# IS31FL3743A Driver {#is31fl3743a-driver} + +I²C 18x11 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 198 single-color LEDs, or 66 RGB LEDs. + +[IS31FL3743A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) + +## Usage {#usage} + +The IS31FL3743A driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3743a` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3743a-mono.c # For single-color +SRC += is31fl3743a.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|-------------------------------|----------------------------------------------------| +|`IS31FL3743A_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3743A_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3743A_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3743A_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3743A_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3743A_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3743A_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3743A_SYNC_1` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 0 | +|`IS31FL3743A_SYNC_2` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 1 | +|`IS31FL3743A_SYNC_3` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 2 | +|`IS31FL3743A_SYNC_4` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 3 | +|`IS31FL3743A_CONFIGURATION` |`0x01` |The value of the configuration register | +|`IS31FL3743A_SW_PULLDOWN` |`IS31FL3743A_PDR_2K_OHM_SW_OFF`|The `SWx` pulldown resistor value | +|`IS31FL3743A_CS_PULLUP` |`IS31FL3743A_PUR_2K_OHM_CS_OFF`|The `CSx` pullup resistor value | +|`IS31FL3743A_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3743A has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3743A_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|---------------------------------|------| +|`IS31FL3743A_I2C_ADDRESS_GND_GND`|`0x20`| +|`IS31FL3743A_I2C_ADDRESS_GND_SCL`|`0x21`| +|`IS31FL3743A_I2C_ADDRESS_GND_SDA`|`0x22`| +|`IS31FL3743A_I2C_ADDRESS_GND_VCC`|`0x23`| +|`IS31FL3743A_I2C_ADDRESS_SCL_GND`|`0x24`| +|`IS31FL3743A_I2C_ADDRESS_SCL_SCL`|`0x25`| +|`IS31FL3743A_I2C_ADDRESS_SCL_SDA`|`0x26`| +|`IS31FL3743A_I2C_ADDRESS_SCL_VCC`|`0x27`| +|`IS31FL3743A_I2C_ADDRESS_SDA_GND`|`0x28`| +|`IS31FL3743A_I2C_ADDRESS_SDA_SCL`|`0x29`| +|`IS31FL3743A_I2C_ADDRESS_SDA_SDA`|`0x2A`| +|`IS31FL3743A_I2C_ADDRESS_SDA_VCC`|`0x2B`| +|`IS31FL3743A_I2C_ADDRESS_VCC_GND`|`0x2C`| +|`IS31FL3743A_I2C_ADDRESS_VCC_SCL`|`0x2D`| +|`IS31FL3743A_I2C_ADDRESS_VCC_SDA`|`0x2E`| +|`IS31FL3743A_I2C_ADDRESS_VCC_VCC`|`0x2F`| + +### Multi-Driver Synchronization {#multi-driver-synchronization} + +Multiple IS31FL3743A drivers can be synchronized by connecting the `SYNC` pins together. One driver must be designated as the "master", and the others configured as "slave". + +To do this, set the `IS31FL3743A_SYNC_n` defines accordingly in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|-------------------------|---------------------------| +|`IS31FL3743A_SYNC_NONE` |No synchronization | +|`IS31FL3743A_SYNC_MASTER`|Driver configured as master| +|`IS31FL3743A_SYNC_SLAVE` |Driver configured as slave | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3743A_SW_PULLDOWN IS31FL3743A_PDR_2K_OHM_SW_OFF +#define IS31FL3743A_CS_PULLUP IS31FL3743A_PUR_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3743A_SW_PULLDOWN` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3743A_PDR_0_OHM` |None (default) | +|`IS31FL3743A_PDR_0K5_OHM_SW_OFF`|0.5 kΩ in SWx off time | +|`IS31FL3743A_PDR_1K_OHM_SW_OFF` |1 kΩ in SWx off time | +|`IS31FL3743A_PDR_2K_OHM_SW_OFF` |2 kΩ in SWx off time (default)| +|`IS31FL3743A_PDR_1K_OHM` |1 kΩ | +|`IS31FL3743A_PDR_2K_OHM` |2 kΩ | +|`IS31FL3743A_PDR_4K_OHM` |4 kΩ | +|`IS31FL3743A_PDR_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3743A_CS_PULLUP` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3743A_PUR_0_OHM` |None (default) | +|`IS31FL3743A_PUR_0K5_OHM_CS_OFF`|0.5 kΩ in CSy off time | +|`IS31FL3743A_PUR_1K_OHM_CS_OFF` |1 kΩ in CSy off time | +|`IS31FL3743A_PUR_2K_OHM_CS_OFF` |2 kΩ in CSy off time (default)| +|`IS31FL3743A_PUR_1K_OHM` |1 kΩ | +|`IS31FL3743A_PUR_2K_OHM` |2 kΩ | +|`IS31FL3743A_PUR_4K_OHM` |4 kΩ | +|`IS31FL3743A_PUR_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSy` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3743A_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3743a_led_t PROGMEM g_is31fl3743a_leds[IS31FL3743A_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3743a_led_t PROGMEM g_is31fl3743a_leds[IS31FL3743A_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 8. + +## API {#api} + +### `struct is31fl3743a_led_t` {#api-is31fl3743a-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3743a-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3743a_init(uint8_t index)` {#api-is31fl3743a-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3743a-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3743a_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3743a-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3743a-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3743a_select_page(uint8_t index, uint8_t page)` {#api-is31fl3743a-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3743a-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3743a_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3743a-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3743a_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3743a-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3743a-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3743a_set_value(int index, uint8_t value)` {#api-is31fl3743a-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3743a_set_value_all(uint8_t value)` {#api-is31fl3743a-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3743a-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3743a_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3743a-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3743a_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3743a-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3743a_update_pwm_buffers(uint8_t index)` {#api-is31fl3743a-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3743a-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3743a_update_scaling_registers(uint8_t index)` {#api-is31fl3743a-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3743a-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3745.md b/docs/drivers/is31fl3745.md new file mode 100644 index 0000000000..f13f029bfe --- /dev/null +++ b/docs/drivers/is31fl3745.md @@ -0,0 +1,320 @@ +# IS31FL3745 Driver {#is31fl3745-driver} + +I²C 18x8 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 144 single-color LEDs, or 48 RGB LEDs. + +[IS31FL3745 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) + +## Usage {#usage} + +The IS31FL3745 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3745` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3745-mono.c # For single-color +SRC += is31fl3745.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|------------------------------|----------------------------------------------------| +|`IS31FL3745_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3745_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3745_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3745_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3745_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3745_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3745_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3745_SYNC_1` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 0 | +|`IS31FL3745_SYNC_2` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 1 | +|`IS31FL3745_SYNC_3` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 2 | +|`IS31FL3745_SYNC_4` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 3 | +|`IS31FL3745_CONFIGURATION` |`0x31` |The value of the configuration register | +|`IS31FL3745_SW_PULLDOWN` |`IS31FL3745_PDR_2K_OHM_SW_OFF`|The `SWx` pulldown resistor value | +|`IS31FL3745_CS_PULLUP` |`IS31FL3745_PUR_2K_OHM_CS_OFF`|The `CSx` pullup resistor value | +|`IS31FL3745_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3745 has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3745_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|--------------------------------|------| +|`IS31FL3745_I2C_ADDRESS_GND_GND`|`0x20`| +|`IS31FL3745_I2C_ADDRESS_GND_SCL`|`0x21`| +|`IS31FL3745_I2C_ADDRESS_GND_SDA`|`0x22`| +|`IS31FL3745_I2C_ADDRESS_GND_VCC`|`0x23`| +|`IS31FL3745_I2C_ADDRESS_SCL_GND`|`0x24`| +|`IS31FL3745_I2C_ADDRESS_SCL_SCL`|`0x25`| +|`IS31FL3745_I2C_ADDRESS_SCL_SDA`|`0x26`| +|`IS31FL3745_I2C_ADDRESS_SCL_VCC`|`0x27`| +|`IS31FL3745_I2C_ADDRESS_SDA_GND`|`0x28`| +|`IS31FL3745_I2C_ADDRESS_SDA_SCL`|`0x29`| +|`IS31FL3745_I2C_ADDRESS_SDA_SDA`|`0x2A`| +|`IS31FL3745_I2C_ADDRESS_SDA_VCC`|`0x2B`| +|`IS31FL3745_I2C_ADDRESS_VCC_GND`|`0x2C`| +|`IS31FL3745_I2C_ADDRESS_VCC_SCL`|`0x2D`| +|`IS31FL3745_I2C_ADDRESS_VCC_SDA`|`0x2E`| +|`IS31FL3745_I2C_ADDRESS_VCC_VCC`|`0x2F`| + +### Multi-Driver Synchronization {#multi-driver-synchronization} + +Multiple IS31FL3745 drivers can be synchronized by connecting the `SYNC` pins together. One driver must be designated as the "master", and the others configured as "slave". + +To do this, set the `IS31FL3745_SYNC_n` defines accordingly in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------|---------------------------| +|`IS31FL3745_SYNC_NONE` |No synchronization | +|`IS31FL3745_SYNC_MASTER`|Driver configured as master| +|`IS31FL3745_SYNC_SLAVE` |Driver configured as slave | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3745_SW_PULLDOWN IS31FL3745_PDR_2K_OHM_SW_OFF +#define IS31FL3745_CS_PULLUP IS31FL3745_PUR_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3745_SW_PULLDOWN` are: + +|Define |Resistance | +|-------------------------------|------------------------------| +|`IS31FL3745_PDR_0_OHM` |None (default) | +|`IS31FL3745_PDR_0K5_OHM_SW_OFF`|0.5 kΩ in SWx off time | +|`IS31FL3745_PDR_1K_OHM_SW_OFF` |1 kΩ in SWx off time | +|`IS31FL3745_PDR_2K_OHM_SW_OFF` |2 kΩ in SWx off time (default)| +|`IS31FL3745_PDR_1K_OHM` |1 kΩ | +|`IS31FL3745_PDR_2K_OHM` |2 kΩ | +|`IS31FL3745_PDR_4K_OHM` |4 kΩ | +|`IS31FL3745_PDR_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3745_CS_PULLUP` are: + +|Define |Resistance | +|-------------------------------|------------------------------| +|`IS31FL3745_PUR_0_OHM` |None (default) | +|`IS31FL3745_PUR_0K5_OHM_CS_OFF`|0.5 kΩ in CSy off time | +|`IS31FL3745_PUR_1K_OHM_CS_OFF` |1 kΩ in CSy off time | +|`IS31FL3745_PUR_2K_OHM_CS_OFF` |2 kΩ in CSy off time (default)| +|`IS31FL3745_PUR_1K_OHM` |1 kΩ | +|`IS31FL3745_PUR_2K_OHM` |2 kΩ | +|`IS31FL3745_PUR_4K_OHM` |4 kΩ | +|`IS31FL3745_PUR_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSy` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3745_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3745_led_t PROGMEM g_is31fl3745_leds[IS31FL3745_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3745_led_t PROGMEM g_is31fl3745_leds[IS31FL3745_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 9. + +## API {#api} + +### `struct is31fl3745_led_t` {#api-is31fl3745-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3745-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3745_init(uint8_t index)` {#api-is31fl3745-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3745-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3745_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3745-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3745-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3745_select_page(uint8_t index, uint8_t page)` {#api-is31fl3745-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3745-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3745_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3745-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3745_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3745_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3745-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3745-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3745_set_value(int index, uint8_t value)` {#api-is31fl3745-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3745_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3745_set_value_all(uint8_t value)` {#api-is31fl3745-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3745-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3745_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3745-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3745_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3745_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3745-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3745_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3745_update_pwm_buffers(uint8_t index)` {#api-is31fl3745-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3745-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3745_update_scaling_registers(uint8_t index)` {#api-is31fl3745-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3745-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3746a.md b/docs/drivers/is31fl3746a.md new file mode 100644 index 0000000000..bdd5c18357 --- /dev/null +++ b/docs/drivers/is31fl3746a.md @@ -0,0 +1,327 @@ +# IS31FL3746A Driver {#is31fl3746a-driver} + +I²C 18x4 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 72 single-color LEDs, or 24 RGB LEDs. + +[IS31FL3746A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) + +## Usage {#usage} + +The IS31FL3746A driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3746a` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3746a-mono.c # For single-color +SRC += is31fl3746a.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|----------------------------------|----------------------------------------------------| +|`IS31FL3746A_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3746A_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3746A_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3746A_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3746A_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3746A_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3746A_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3746A_CONFIGURATION` |`0x01` |The value of the configuration register | +|`IS31FL3746A_PWM_FREQUENCY` |`IS31FL3746A_PWM_FREQUENCY_29K_HZ`|The PWM frequency of the LEDs | +|`IS31FL3746A_SW_PULLDOWN` |`IS31FL3746A_PDR_2K_OHM_SW_OFF` |The `SWx` pulldown resistor value | +|`IS31FL3746A_CS_PULLUP` |`IS31FL3746A_PUR_2K_OHM_CS_OFF` |The `CSx` pullup resistor value | +|`IS31FL3746A_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3746A has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3746A_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|---------------------------------|------| +|`IS31FL3746A_I2C_ADDRESS_GND_GND`|`0x60`| +|`IS31FL3746A_I2C_ADDRESS_GND_SCL`|`0x61`| +|`IS31FL3746A_I2C_ADDRESS_GND_SDA`|`0x62`| +|`IS31FL3746A_I2C_ADDRESS_GND_VCC`|`0x63`| +|`IS31FL3746A_I2C_ADDRESS_SCL_GND`|`0x64`| +|`IS31FL3746A_I2C_ADDRESS_SCL_SCL`|`0x65`| +|`IS31FL3746A_I2C_ADDRESS_SCL_SDA`|`0x66`| +|`IS31FL3746A_I2C_ADDRESS_SCL_VCC`|`0x67`| +|`IS31FL3746A_I2C_ADDRESS_SDA_GND`|`0x68`| +|`IS31FL3746A_I2C_ADDRESS_SDA_SCL`|`0x69`| +|`IS31FL3746A_I2C_ADDRESS_SDA_SDA`|`0x6A`| +|`IS31FL3746A_I2C_ADDRESS_SDA_VCC`|`0x6B`| +|`IS31FL3746A_I2C_ADDRESS_VCC_GND`|`0x6C`| +|`IS31FL3746A_I2C_ADDRESS_VCC_SCL`|`0x6D`| +|`IS31FL3746A_I2C_ADDRESS_VCC_SDA`|`0x6E`| +|`IS31FL3746A_I2C_ADDRESS_VCC_VCC`|`0x6F`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted by adding the following to your `config.h`: + +```c +#define IS31FL3746A_PWM_FREQUENCY IS31FL3746A_PWM_FREQUENCY_29K_HZ +``` + +Valid values are: + +|Define |Frequency | +|-----------------------------------|----------------| +|`IS31FL3746A_PWM_FREQUENCY_29K_HZ` |29 kHz (default)| +|`IS31FL3746A_PWM_FREQUENCY_14K5_HZ`|14.5 kHz | +|`IS31FL3746A_PWM_FREQUENCY_7K25_HZ`|7.25 kHz | +|`IS31FL3746A_PWM_FREQUENCY_3K63_HZ`|3.63 kHz | +|`IS31FL3746A_PWM_FREQUENCY_1K81_HZ`|1.81 kHz | +|`IS31FL3746A_PWM_FREQUENCY_906_HZ` |906 Hz | +|`IS31FL3746A_PWM_FREQUENCY_453_HZ` |453 Hz | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3746A_SW_PULLDOWN IS31FL3746A_PDR_2K_OHM_SW_OFF +#define IS31FL3746A_CS_PULLUP IS31FL3746A_PUR_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3746A_SW_PULLDOWN` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3746A_PDR_0_OHM` |None | +|`IS31FL3746A_PDR_0K5_OHM_SW_OFF`|0.5 kΩ in SWx off time | +|`IS31FL3746A_PDR_1K_OHM_SW_OFF` |1 kΩ in SWx off time | +|`IS31FL3746A_PDR_2K_OHM_SW_OFF` |2 kΩ in SWx off time (default)| +|`IS31FL3746A_PDR_1K_OHM` |1 kΩ | +|`IS31FL3746A_PDR_2K_OHM` |2 kΩ | +|`IS31FL3746A_PDR_4K_OHM` |4 kΩ | +|`IS31FL3746A_PDR_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3746A_CS_PULLUP` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3746A_PUR_0_OHM` |None (default) | +|`IS31FL3746A_PUR_0K5_OHM_CS_OFF`|0.5 kΩ in CSy off time | +|`IS31FL3746A_PUR_1K_OHM_CS_OFF` |1 kΩ in CSy off time | +|`IS31FL3746A_PUR_2K_OHM_CS_OFF` |2 kΩ in CSy off time (default)| +|`IS31FL3746A_PUR_1K_OHM` |1 kΩ | +|`IS31FL3746A_PUR_2K_OHM` |2 kΩ | +|`IS31FL3746A_PUR_4K_OHM` |4 kΩ | +|`IS31FL3746A_PUR_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSy` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3746A_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const is31fl3746a_led_t PROGMEM g_is31fl3746a_leds[IS31FL3746A_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3746a_led_t PROGMEM g_is31fl3746a_leds[IS31FL3746A_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 13, figure 8. + +## API {#api} + +### `struct is31fl3746a_led_t` {#api-is31fl3746a-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3746a-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3746a_init(uint8_t index)` {#api-is31fl3746a-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3746a-init-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t sync` + Sync configuration of the LED driver. + +--- + +### `void is31fl3746a_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3746a-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3746a-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3746a_select_page(uint8_t index, uint8_t page)` {#api-is31fl3746a-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3746a-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3746a_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3746a-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3746a_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3746a-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3746a-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3746a_set_value(int index, uint8_t value)` {#api-is31fl3746a-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3746a_set_value_all(uint8_t value)` {#api-is31fl3746a-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3746a-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3746a_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3746a-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3746a_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3746a-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3746a_update_pwm_buffers(uint8_t index)` {#api-is31fl3746a-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3746a-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3746a_update_scaling_registers(uint8_t index)` {#api-is31fl3746a-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3746a-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/snled27351.md b/docs/drivers/snled27351.md new file mode 100644 index 0000000000..1d91182f7c --- /dev/null +++ b/docs/drivers/snled27351.md @@ -0,0 +1,245 @@ +# SNLED27351 Driver {#snled27351-driver} + +I²C 16x12 LED matrix driver by Sonix. Supports a maximum of four drivers, each controlling up to 192 single-color LEDs, or 64 RGB LEDs. + +A slightly modified version of this IC is also known as "CKLED2001". + +[SNLED27351 Datasheet](https://www.sonix.com.tw/files/1/D235860C0C037C28E050007F01001CBE) + +## Usage {#usage} + +The SNLED27351 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `snled27351` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led +SRC += snled27351-mono.c # For single-color +SRC += snled27351.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`SNLED27351_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`SNLED27351_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`SNLED27351_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`SNLED27351_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`SNLED27351_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`SNLED27351_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`SNLED27351_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | + +### I²C Addressing {#i2c-addressing} + +The SNLED27351 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `SNLED27351_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------------|------| +|`SNLED27351_I2C_ADDRESS_GND` |`0x74`| +|`SNLED27351_I2C_ADDRESS_SCL` |`0x75`| +|`SNLED27351_I2C_ADDRESS_SDA` |`0x76`| +|`SNLED27351_I2C_ADDRESS_VDDIO`|`0x77`| + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: + +```c +const snled27351_led_t PROGMEM g_snled27351_leds[SNLED27351_LED_COUNT] = { +/* Driver + * | R G B */ + {0, CB1_CA1, CB1_CA2, CB1_CA3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `CB1` pin, and their anodes on the `CA1`, `CA2` and `CA3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const snled27351_led_t PROGMEM g_snled27351_leds[SNLED27351_LED_COUNT] = { +/* Driver + * | V */ + {0, CB1_CA1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 13. + +## API {#api} + +### `struct snled27351_led_t` {#api-snled27351-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-snled27351-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void snled27351_init(uint8_t index)` {#api-snled27351-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-snled27351-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void snled27351_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-snled27351-write-register} + +Set the value of the given register. + +#### Arguments {#api-snled27351-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void snled27351_select_page(uint8_t index, uint8_t page)` {#api-snled27351-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-snled27351-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void snled27351_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-snled27351-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `snled27351_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-snled27351-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void snled27351_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-snled27351-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-snled27351-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void snled27351_set_value(int index, uint8_t value)` {#api-snled27351-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `snled27351_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-snled27351-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void snled27351_set_value_all(uint8_t value)` {#api-snled27351-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-snled27351-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void snled27351_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-snled27351-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `snled27351_update_led_control_registers()` after you are finished. + +#### Arguments {#api-snled27351-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void snled27351_set_led_control_register(uint8_t index, bool value)` {#api-snled27351-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `snled27351_update_led_control_registers()` after you are finished. + +#### Arguments {#api-snled27351-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void snled27351_update_pwm_buffers(uint8_t index)` {#api-snled27351-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-snled27351-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void snled27351_update_led_control_registers(uint8_t index)` {#api-snled27351-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-snled27351-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. 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_` 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 `.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 = +LED_MATRIX_DRIVER = is31fl3218 ``` -Where `` 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_` 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_` | (Required) Address for the additional LED drivers | | -| `ISSI_SSR_` | (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 `.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 `.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/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_` 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 `.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_` 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 `.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_` 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 `.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_` 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 `.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 = -``` - -Where `` 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_` 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_` | (Required) Address for the additional RGB drivers | | -| `ISSI_SSR_` | (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 `.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_`. 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 `.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__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 `.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: -- cgit v1.2.3 From 8abaa3bc2df4fda13a96d0c5c4ce74b70c974fb7 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Tue, 16 Jul 2024 09:22:17 +1000 Subject: Add support for key override introspection. (#24120) --- docs/ChangeLog/PR24120.md | 19 ++++++++++++ docs/features/key_overrides.md | 17 +++++----- quantum/keymap_introspection.c | 43 +++++++++++++++++++++++--- quantum/keymap_introspection.h | 21 +++++++++++++ quantum/process_keycode/process_key_override.c | 10 +++--- quantum/process_keycode/process_key_override.h | 5 +-- 6 files changed, 90 insertions(+), 25 deletions(-) create mode 100644 docs/ChangeLog/PR24120.md (limited to 'docs/features') diff --git a/docs/ChangeLog/PR24120.md b/docs/ChangeLog/PR24120.md new file mode 100644 index 0000000000..5c635349ea --- /dev/null +++ b/docs/ChangeLog/PR24120.md @@ -0,0 +1,19 @@ +## Changes requiring user action + +### Key Override Introspection + +Changes were made to key overrides in order to hook them into the keymap introspection system. + +Key override signature changed from: + +```c +const key_override_t **key_overrides = (const key_override_t *[]){ +``` + +to: + +```c +const key_override_t *key_overrides[] = { +``` + +The list of key overrides now does not need to be `NULL`-terminated. 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/quantum/keymap_introspection.c b/quantum/keymap_introspection.c index 4e95125335..327df6e277 100644 --- a/quantum/keymap_introspection.c +++ b/quantum/keymap_introspection.c @@ -10,6 +10,7 @@ #endif // INTROSPECTION_KEYMAP_C #include "keymap_introspection.h" +#include "util.h" //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// // Key mapping @@ -83,7 +84,7 @@ uint16_t keycode_at_dip_switch_map_location_raw(uint8_t switch_idx, bool on) { return KC_TRNS; } -uint16_t keycode_at_dip_switch_map_location(uint8_t switch_idx, bool on) { +__attribute__((weak)) uint16_t keycode_at_dip_switch_map_location(uint8_t switch_idx, bool on) { return keycode_at_dip_switch_map_location_raw(switch_idx, on); } @@ -95,13 +96,16 @@ uint16_t keycode_at_dip_switch_map_location(uint8_t switch_idx, bool on) { #if defined(COMBO_ENABLE) uint16_t combo_count_raw(void) { - return sizeof(key_combos) / sizeof(combo_t); + return ARRAY_SIZE(key_combos); } __attribute__((weak)) uint16_t combo_count(void) { return combo_count_raw(); } combo_t* combo_get_raw(uint16_t combo_idx) { + if (combo_idx >= combo_count_raw()) { + return NULL; + } return &key_combos[combo_idx]; } __attribute__((weak)) combo_t* combo_get(uint16_t combo_idx) { @@ -116,19 +120,48 @@ __attribute__((weak)) combo_t* combo_get(uint16_t combo_idx) { #if defined(TAP_DANCE_ENABLE) uint16_t tap_dance_count_raw(void) { - return sizeof(tap_dance_actions) / sizeof(tap_dance_action_t); + return ARRAY_SIZE(tap_dance_actions); } -uint16_t tap_dance_count(void) { +__attribute__((weak)) uint16_t tap_dance_count(void) { return tap_dance_count_raw(); } tap_dance_action_t* tap_dance_get_raw(uint16_t tap_dance_idx) { + if (tap_dance_idx >= tap_dance_count_raw()) { + return NULL; + } return &tap_dance_actions[tap_dance_idx]; } -tap_dance_action_t* tap_dance_get(uint16_t tap_dance_idx) { +__attribute__((weak)) tap_dance_action_t* tap_dance_get(uint16_t tap_dance_idx) { return tap_dance_get_raw(tap_dance_idx); } #endif // defined(TAP_DANCE_ENABLE) + +//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// +// Key Overrides + +#if defined(KEY_OVERRIDE_ENABLE) + +uint16_t key_override_count_raw(void) { + return ARRAY_SIZE(key_overrides); +} + +__attribute__((weak)) uint16_t key_override_count(void) { + return key_override_count_raw(); +} + +const key_override_t* key_override_get_raw(uint16_t key_override_idx) { + if (key_override_idx >= key_override_count_raw()) { + return NULL; + } + return key_overrides[key_override_idx]; +} + +__attribute__((weak)) const key_override_t* key_override_get(uint16_t key_override_idx) { + return key_override_get_raw(key_override_idx); +} + +#endif // defined(KEY_OVERRIDE_ENABLE) diff --git a/quantum/keymap_introspection.h b/quantum/keymap_introspection.h index bc4dd93b4c..719825c674 100644 --- a/quantum/keymap_introspection.h +++ b/quantum/keymap_introspection.h @@ -88,3 +88,24 @@ tap_dance_action_t* tap_dance_get_raw(uint16_t tap_dance_idx); tap_dance_action_t* tap_dance_get(uint16_t tap_dance_idx); #endif // defined(TAP_DANCE_ENABLE) + +//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// +// Key Overrides + +#if defined(KEY_OVERRIDE_ENABLE) + +// Forward declaration of key_override_t so we don't need to deal with header reordering +struct key_override_t; +typedef struct key_override_t key_override_t; + +// Get the number of key overrides defined in the user's keymap, stored in firmware rather than any other persistent storage +uint16_t key_override_count_raw(void); +// Get the number of key overrides defined in the user's keymap, potentially stored dynamically +uint16_t key_override_count(void); + +// Get the key override definitions, stored in firmware rather than any other persistent storage +const key_override_t* key_override_get_raw(uint16_t key_override_idx); +// Get the key override definitions, potentially stored dynamically +const key_override_t* key_override_get(uint16_t key_override_idx); + +#endif // defined(KEY_OVERRIDE_ENABLE) diff --git a/quantum/process_keycode/process_key_override.c b/quantum/process_keycode/process_key_override.c index 264e2562b8..ce30477ee8 100644 --- a/quantum/process_keycode/process_key_override.c +++ b/quantum/process_keycode/process_key_override.c @@ -23,6 +23,7 @@ #include "action_util.h" #include "quantum.h" #include "quantum_keycodes.h" +#include "keymap_introspection.h" #ifndef KEY_OVERRIDE_REPEAT_DELAY # define KEY_OVERRIDE_REPEAT_DELAY 500 @@ -83,9 +84,6 @@ static uint16_t deferred_register = 0; // TODO: in future maybe save in EEPROM? static bool enabled = true; -// Public variables -__attribute__((weak)) const key_override_t **key_overrides = NULL; - // Forward decls static const key_override_t *clear_active_override(const bool allow_reregister); @@ -247,12 +245,12 @@ static bool check_activation_event(const key_override_t *override, const bool ke /** Iterates through the list of key overrides and tries activating each, until it finds one that activates or reaches the end of overrides. Returns true if the key action for `keycode` should be sent */ static bool try_activating_override(const uint16_t keycode, const uint8_t layer, const bool key_down, const bool is_mod, const uint8_t active_mods, bool *activated) { - if (key_overrides == NULL) { + if (key_override_count() == 0) { return true; } - for (uint8_t i = 0;; i++) { - const key_override_t *const override = key_overrides[i]; + for (uint8_t i = 0; i < key_override_count(); i++) { + const key_override_t *const override = key_override_get(i); // End of array if (override == NULL) { diff --git a/quantum/process_keycode/process_key_override.h b/quantum/process_keycode/process_key_override.h index 3e37c7e63a..9ec84dbe6e 100644 --- a/quantum/process_keycode/process_key_override.h +++ b/quantum/process_keycode/process_key_override.h @@ -55,7 +55,7 @@ typedef enum { } ko_option_t; /** Defines a single key override */ -typedef struct { +typedef struct key_override_t { // The non-modifier keycode that triggers the override. This keycode, and the necessary modifiers (trigger_mods) must be pressed to activate this override. Set this to the keycode of the key that should activate the override. Set to KC_NO to require only the necessary modifiers to be pressed and no non-modifier. uint16_t trigger; @@ -87,9 +87,6 @@ typedef struct { bool *enabled; } key_override_t; -/** Define this as a null-terminated array of pointers to key overrides. These key overrides will be used by qmk. */ -extern const key_override_t **key_overrides; - /** Turns key overrides on */ void key_override_on(void); -- cgit v1.2.3 From 21b84596e7c372eeeedcf41a32c6c25379cd8f0e Mon Sep 17 00:00:00 2001 From: フィルターペーパー <76888457+filterpaper@users.noreply.github.com> Date: Mon, 19 Aug 2024 10:18:28 +0800 Subject: Enhance overlapping mouse keys control (#23341) Enhance the overlapping mouse key press acceleration (introduced in #21494) with user preprocessor controls. --- docs/features/mouse_keys.md | 13 +++++++++++++ quantum/mousekey.c | 10 +++++----- quantum/mousekey.h | 10 ++++++++++ 3 files changed, 28 insertions(+), 5 deletions(-) (limited to 'docs/features') diff --git a/docs/features/mouse_keys.md b/docs/features/mouse_keys.md index 4cc06c992a..d755084f8e 100644 --- a/docs/features/mouse_keys.md +++ b/docs/features/mouse_keys.md @@ -203,6 +203,19 @@ Tips: * Keep `MOUSEKEY_MOVE_DELTA` at 1. This allows precise movements before the gliding effect starts. * Mouse wheel options are the same as the default accelerated mode, and do not use inertia. +### Overlapping mouse key control + +When additional overlapping mouse key is pressed, the mouse cursor will continue in a new direction with the same acceleration. The following settings can be used to reset the acceleration with new overlapping keys for more precise control if desired: + +|Define |Default |Description | +|------------------------------|----------------------|-----------------------------------------------------------------------| +|`MOUSEKEY_OVERLAP_RESET` |undefined |Enables overlapping mouse key control | +|`MOUSEKEY_OVERLAP_MOVE_DELTA` |`MOUSEKEY_MOVE_DELTA` |Step size of reset movement acceleration | +|`MOUSEKEY_OVERLAP_WHEEL_DELTA`|`MOUSEKEY_WHEEL_DELTA`|Step size of reset mouse wheel acceleration | +|`MOUSEKEY_OVERLAP_INTERVAL` |`MOUSEKEY_INTERVAL` |Reset time between cursor movements in milliseconds (Kinetic mode only)| + +?> This feature will not be applied on Inertial mode + ## Use with PS/2 Mouse and Pointing Device Mouse keys button state is shared with [PS/2 mouse](ps2_mouse) and [pointing device](pointing_device) so mouse keys button presses can be used for clicks and drags. diff --git a/quantum/mousekey.c b/quantum/mousekey.c index 8683cfdffa..9649943a0d 100644 --- a/quantum/mousekey.c +++ b/quantum/mousekey.c @@ -391,18 +391,18 @@ void mousekey_on(uint8_t code) { } # endif -# ifndef MOUSEKEY_INERTIA +# if defined(MOUSEKEY_OVERLAP_RESET) && !defined(MOUSEKEY_INERTIA) // If mouse report is not zero, the current mousekey press is overlapping // with another. Restart acceleration for smoother directional transition. if (mouse_report.x || mouse_report.y || mouse_report.h || mouse_report.v) { # ifdef MK_KINETIC_SPEED - mouse_timer = timer_read() - (MOUSEKEY_INTERVAL << 2); + mouse_timer = timer_read() - MOUSEKEY_OVERLAP_INTERVAL; # else - mousekey_repeat = MOUSEKEY_MOVE_DELTA; - mousekey_wheel_repeat = MOUSEKEY_WHEEL_DELTA; + mousekey_repeat = MOUSEKEY_OVERLAP_MOVE_DELTA; + mousekey_wheel_repeat = MOUSEKEY_OVERLAP_WHEEL_DELTA; # endif } -# endif // ifndef MOUSEKEY_INERTIA +# endif // defined(MOUSEKEY_OVERLAP_RESET) && !defined(MOUSEKEY_INERTIA) # ifdef MOUSEKEY_INERTIA diff --git a/quantum/mousekey.h b/quantum/mousekey.h index 73380b743a..e7a790b9a9 100644 --- a/quantum/mousekey.h +++ b/quantum/mousekey.h @@ -174,6 +174,16 @@ along with this program. If not, see . #endif /* #ifndef MK_3_SPEED */ +#ifndef MOUSEKEY_OVERLAP_MOVE_DELTA +# define MOUSEKEY_OVERLAP_MOVE_DELTA MOUSEKEY_MOVE_DELTA +#endif +#ifndef MOUSEKEY_OVERLAP_WHEEL_DELTA +# define MOUSEKEY_OVERLAP_WHEEL_DELTA MOUSEKEY_WHEEL_DELTA +#endif +#ifndef MOUSEKEY_OVERLAP_INTERVAL +# define MOUSEKEY_OVERLAP_INTERVAL MOUSEKEY_INTERVAL +#endif + #ifdef __cplusplus extern "C" { #endif -- cgit v1.2.3