3 files changed, 38 insertions, 2 deletions

diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index a9e711c9f..7b597143c 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -296,6 +296,19 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 |`#define DISABLE_RGB_MATRIX_SOLID_SPLASH`              |Disables `RGB_MATRIX_SOLID_SPLASH`             |
 |`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH`         |Disables `RGB_MATRIX_SOLID_MULTISPLASH`        |
 
+### RGB Matrix Effect Typing Heatmap :id=rgb-matrix-effect-typing-heatmap
+
+This effect will color the RGB matrix 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
+`RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS`:
+
+```c
+#define RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 50
+```
 
 ## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
 
diff --git a/quantum/rgb_matrix_animations/typing_heatmap_anim.h b/quantum/rgb_matrix_animations/typing_heatmap_anim.h
index b855fdc19..e06437bf7 100644
--- a/quantum/rgb_matrix_animations/typing_heatmap_anim.h
+++ b/quantum/rgb_matrix_animations/typing_heatmap_anim.h
@@ -2,6 +2,10 @@
 RGB_MATRIX_EFFECT(TYPING_HEATMAP)
 #    ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
 
+#        ifndef RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS
+#            define RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 25
+#        endif
+
 void process_rgb_matrix_typing_heatmap(keyrecord_t* record) {
     uint8_t row   = record->event.key.row;
     uint8_t col   = record->event.key.col;
@@ -27,6 +31,11 @@ void process_rgb_matrix_typing_heatmap(keyrecord_t* record) {
     }
 }
 
+// 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) {
     // Modified version of RGB_MATRIX_USE_LIMITS to work off of matrix row / col size
     uint8_t led_min = RGB_MATRIX_LED_PROCESS_LIMIT * params->iter;
@@ -38,6 +47,18 @@ bool TYPING_HEATMAP(effect_params_t* params) {
         memset(g_rgb_frame_buffer, 0, sizeof g_rgb_frame_buffer);
     }
 
+    // The heatmap animation might run in several iterations depending on
+    // `RGB_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) >= RGB_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
     for (int i = led_min; i < led_max; i++) {
         uint8_t row = i % MATRIX_ROWS;
@@ -55,7 +76,9 @@ bool TYPING_HEATMAP(effect_params_t* params) {
             rgb_matrix_set_color(led[j], rgb.r, rgb.g, rgb.b);
         }
 
-        g_rgb_frame_buffer[row][col] = qsub8(val, 1);
+        if (decrease_heatmap_values) {
+            g_rgb_frame_buffer[row][col] = qsub8(val, 1);
+        }
     }
 
     return led_max < sizeof(g_rgb_frame_buffer);
diff --git a/shell.nix b/shell.nix
index 6cfda2da9..82505d5d2 100644
--- a/shell.nix
+++ b/shell.nix
@@ -71,7 +71,7 @@ in
 mkShell {
   name = "qmk-firmware";
 
-  buildInputs = [ dfu-programmer dfu-util diffutils git pythonEnv ]
+  buildInputs = [ clang-tools dfu-programmer dfu-util diffutils git pythonEnv ]
     ++ lib.optional avr [
       pkgsCross.avr.buildPackages.binutils
       pkgsCross.avr.buildPackages.gcc8