From 140de696a2e66061a550575437ed33faaa983067 Mon Sep 17 00:00:00 2001 From: zvecr Date: Sat, 27 Jun 2026 15:54:20 +0100 Subject: [PATCH] Port typing_heatmap animation to LED Matrix --- docs/features/led_matrix.md | 45 +++++++ .../animations/led_matrix_effects.inc | 1 + .../animations/typing_heatmap_anim.h | 112 ++++++++++++++++++ quantum/led_matrix/post_config.h | 5 + 4 files changed, 163 insertions(+) create mode 100644 quantum/led_matrix/animations/typing_heatmap_anim.h diff --git a/docs/features/led_matrix.md b/docs/features/led_matrix.md index f14fb47d62d7..7cc5f7a4899d 100644 --- a/docs/features/led_matrix.md +++ b/docs/features/led_matrix.md @@ -119,6 +119,7 @@ enum led_matrix_effects { LED_MATRIX_SOLID_MULTISPLASH, // Value pulses away from multiple key hits then fades out LED_MATRIX_WAVE_LEFT_RIGHT, // Sine wave scrolling from left to right LED_MATRIX_WAVE_UP_DOWN, // Sine wave scrolling from up to down + LED_MATRIX_TYPING_HEATMAP, // How hot is your WPM! LED_MATRIX_EFFECT_MAX }; ``` @@ -140,6 +141,14 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Enables `LED_MATRIX_WAVE_LEFT_RIGHT` | |`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN` |Enables `LED_MATRIX_WAVE_UP_DOWN` | +|Framebuffer Defines |Description | +|------------------------------------------------------|-----------------------------------------------| +|`#define ENABLE_LED_MATRIX_TYPING_HEATMAP` |Enables `LED_MATRIX_TYPING_HEATMAP` | + +::: tip +These modes introduce additional logic that can increase firmware size. +::: + |Reactive Defines |Description | |-------------------------------------------------------|----------------------------------------------| |`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` | @@ -156,6 +165,42 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi These modes introduce additional logic that can increase firmware size. ::: +### LED Matrix Effect Typing Heatmap {#led-matrix-effect-typing-heatmap} + +This effect will scale the LED matrix brightness according to a heatmap of recently pressed keys. Whenever a key is pressed its "temperature" increases as well as that of its neighboring keys. The temperature of each key is then decreased automatically every 25 milliseconds by default. + +In order to change the delay of temperature decrease define `LED_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS`: + +```c +#define LED_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 50 +``` + +As heatmap uses the physical position of the leds set in the g_led_config, you may need to tweak the following options to get the best effect for your keyboard. Note the size of this grid is `224x64`. + +Limit the distance the effect spreads to surrounding keys. + +```c +#define LED_MATRIX_TYPING_HEATMAP_SPREAD 40 +``` + +Limit how hot surrounding keys get from each press. + +```c +#define LED_MATRIX_TYPING_HEATMAP_AREA_LIMIT 16 +``` + +Remove the spread effect entirely. + +```c +#define LED_MATRIX_TYPING_HEATMAP_SLIM +``` + +It's also possible to adjust the tempo of *heating up*. It's defined as the number of steps by which to increment the brightness. Decreasing this value increases the number of keystrokes needed to fully heat up the key. + +```c +#define LED_MATRIX_TYPING_HEATMAP_INCREASE_STEP 32 +``` + ## Custom LED Matrix Effects {#custom-led-matrix-effects} By setting `LED_MATRIX_CUSTOM_USER = yes` in `rules.mk`, new effects can be defined directly from your keymap or userspace, without having to edit any QMK core files. To declare new effects, create a `led_matrix_user.inc` file in the user keymap directory or userspace folder. diff --git a/quantum/led_matrix/animations/led_matrix_effects.inc b/quantum/led_matrix/animations/led_matrix_effects.inc index ad1f46b2422c..238e25d24b3d 100644 --- a/quantum/led_matrix/animations/led_matrix_effects.inc +++ b/quantum/led_matrix/animations/led_matrix_effects.inc @@ -16,3 +16,4 @@ #include "solid_splash_anim.h" #include "wave_left_right_anim.h" #include "wave_up_down_anim.h" +#include "typing_heatmap_anim.h" diff --git a/quantum/led_matrix/animations/typing_heatmap_anim.h b/quantum/led_matrix/animations/typing_heatmap_anim.h new file mode 100644 index 000000000000..84dee22f5a92 --- /dev/null +++ b/quantum/led_matrix/animations/typing_heatmap_anim.h @@ -0,0 +1,112 @@ +#if defined(LED_MATRIX_FRAMEBUFFER_EFFECTS) && defined(ENABLE_LED_MATRIX_TYPING_HEATMAP) +LED_MATRIX_EFFECT(TYPING_HEATMAP) +# ifdef LED_MATRIX_CUSTOM_EFFECT_IMPLS +# ifndef LED_MATRIX_TYPING_HEATMAP_INCREASE_STEP +# define LED_MATRIX_TYPING_HEATMAP_INCREASE_STEP 32 +# endif + +# ifndef LED_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS +# define LED_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 25 +# endif + +# ifndef LED_MATRIX_TYPING_HEATMAP_SPREAD +# define LED_MATRIX_TYPING_HEATMAP_SPREAD 40 +# endif + +# ifndef LED_MATRIX_TYPING_HEATMAP_AREA_LIMIT +# define LED_MATRIX_TYPING_HEATMAP_AREA_LIMIT 16 +# endif +void process_led_matrix_typing_heatmap(uint8_t row, uint8_t col) { +# ifdef LED_MATRIX_TYPING_HEATMAP_SLIM + // Limit effect to pressed keys + g_led_frame_buffer[row][col] = qadd8(g_led_frame_buffer[row][col], LED_MATRIX_TYPING_HEATMAP_INCREASE_STEP); +# else + if (g_led_config.matrix_co[row][col] == NO_LED) { // skip as pressed key doesn't have an led position + return; + } + for (uint8_t i_row = 0; i_row < MATRIX_ROWS; i_row++) { + for (uint8_t i_col = 0; i_col < MATRIX_COLS; i_col++) { + if (g_led_config.matrix_co[i_row][i_col] == NO_LED) { // skip as target key doesn't have an led position + continue; + } + if (i_row == row && i_col == col) { + g_led_frame_buffer[row][col] = qadd8(g_led_frame_buffer[row][col], LED_MATRIX_TYPING_HEATMAP_INCREASE_STEP); + } else { +# define LED_DISTANCE(led_a, led_b) sqrt16(((int32_t)(led_a.x - led_b.x) * (int32_t)(led_a.x - led_b.x)) + ((int32_t)(led_a.y - led_b.y) * (int32_t)(led_a.y - led_b.y))) + uint8_t distance = LED_DISTANCE(g_led_config.point[g_led_config.matrix_co[row][col]], g_led_config.point[g_led_config.matrix_co[i_row][i_col]]); +# undef LED_DISTANCE + if (distance <= LED_MATRIX_TYPING_HEATMAP_SPREAD) { + uint8_t amount = qsub8(LED_MATRIX_TYPING_HEATMAP_SPREAD, distance); + if (amount > LED_MATRIX_TYPING_HEATMAP_AREA_LIMIT) { + amount = LED_MATRIX_TYPING_HEATMAP_AREA_LIMIT; + } + g_led_frame_buffer[i_row][i_col] = qadd8(g_led_frame_buffer[i_row][i_col], amount); + } + } + } + } +# endif +} + +// A timer to track the last time we decremented all heatmap values. +static uint16_t heatmap_decrease_timer; +// Whether we should decrement the heatmap values during the next update. +static bool decrease_heatmap_values; + +bool TYPING_HEATMAP(effect_params_t* params) { + LED_MATRIX_USE_LIMITS(led_min, led_max); + + if (params->init) { + led_matrix_set_value_all(0); + memset(g_led_frame_buffer, 0, sizeof g_led_frame_buffer); + } + + // The heatmap animation might run in several iterations depending on + // `LED_MATRIX_LED_PROCESS_LIMIT`, therefore we only want to update the + // timer when the animation starts. + if (params->iter == 0) { + decrease_heatmap_values = timer_elapsed(heatmap_decrease_timer) >= LED_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS; + + // Restart the timer if we are going to decrease the heatmap this frame. + if (decrease_heatmap_values) { + heatmap_decrease_timer = timer_read(); + } + } + + // Render heatmap & decrease + uint8_t count = 0; + for (uint8_t row = 0; row < MATRIX_ROWS && count < LED_MATRIX_LED_PROCESS_LIMIT; row++) { + for (uint8_t col = 0; col < MATRIX_COLS && LED_MATRIX_LED_PROCESS_LIMIT; col++) { + uint8_t val = g_led_frame_buffer[row][col]; + + bool processed = false; + + uint8_t led[LED_HITS_TO_REMEMBER]; + uint8_t led_count = led_matrix_map_row_column_to_led(row, col, led); + for (uint8_t index = 0; index < led_count; index++) { + uint8_t led_index = led[index]; + + if (led_index >= led_min && led_index < led_max) { + count++; + + if (!HAS_ANY_FLAGS(g_led_config.flags[led_index], params->flags)) { + continue; + } + + uint8_t value = scale8(led_matrix_eeconfig.val, val); + led_matrix_set_value(led_index, value); + processed = true; + } + } + + if (processed && decrease_heatmap_values) { + g_led_frame_buffer[row][col] = qsub8(val, 1); + } + } + } + + return led_matrix_check_finished_leds(led_max); +} + +# endif // LED_MATRIX_CUSTOM_EFFECT_IMPLS +#endif // defined(LED_MATRIX_FRAMEBUFFER_EFFECTS) && defined(ENABLE_LED_MATRIX_TYPING_HEATMAP) diff --git a/quantum/led_matrix/post_config.h b/quantum/led_matrix/post_config.h index b6770b9ee1c8..070976fdaac6 100644 --- a/quantum/led_matrix/post_config.h +++ b/quantum/led_matrix/post_config.h @@ -5,6 +5,11 @@ // clang-format off +// framebuffer +#if defined(ENABLE_LED_MATRIX_TYPING_HEATMAP) +# define LED_MATRIX_FRAMEBUFFER_EFFECTS +#endif + // reactive #if defined(ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE) || \ defined(ENABLE_LED_MATRIX_SOLID_REACTIVE_WIDE) || \