tmk_core/doc/hook.md

   1 Hooks
   2 -----
   3 Hooks allow you to execute custom code at certain predefined points in the firmware execution. To use them, just define the hook function in your keymap file.
   4
   5 The following hooks are available available:
   6
   7 Hook function                   | Timing
   8 --------------------------------|-----------------------------------------------
   9 `void hook_early_init(void)`         | Early in the boot process, before the matrix is initialized and before a connection is made with the host. Thus, this hook has access to very few parameters, but it is a good place to define any custom parameters needed by other early processes.
  10 `void hook_late_init(void)`          | Near the end of the boot process, after Boot Magic has run and LEDs have been initialized.
  11 `void hook_bootmagic(void)`          | During the Boot Magic window, after EEPROM and Bootloader checks are made, but before any other built-in Boot Magic checks are made.
  12 `void hook_usb_startup_wait_loop(void)` | Continuously, until the device gets ready and into USB configured state.
  13 `void hook_usb_wakeup(void)`         | When the device wakes up from USB suspend state.
  14 `void hook_usb_suspend_entry(void)`  | When the device enters USB suspend state.
  15 `void hook_usb_suspend_loop(void)`   | Continuously, while the device is in USB suspend state. *Default action:* power down and periodically check the matrix, causing wakeup if needed.
  16 `void hook_keyboard_loop(void)`      | Continuously, during the main loop, after the matrix is checked.
  17 `void hook_matrix_change(keyevent_t event)`      | When a matrix state change is detected, before any other actions are processed.
  18 `void hook_layer_change(uint32_t layer_state)`   | When any layer is changed.
  19 `void hook_default_layer_change(uint32_t default_layer_state)`   | When any default layer is changed.
  20 `void hook_keyboard_leds_change(uint8_t led_status)`             | Whenever a change in the LED status is performed. *Default action:* call `keyboard_set_leds(led_status)`
  21 `bool hook_process_action(keyrecord_t *record)`                  | Before key event is processed by tmk_core. Return true if the event is consumed and default action is not needed.
  22
  23
  24
  25
  26
  27 ### Hooks Examples
  28
  29 You can try these out by copying the code to your keymap file, or any .c file in the Makefile `SRC`.
  30
  31 #### Activate keymap layer 5 on startup
  32
  33 ```C
  34 #include "action_layer.h"
  35
  36 void hook_late_init(void)
  37 {
  38     layer_on(5);
  39     print("Layer 5 enabled!");
  40 }
  41 ```
  42
  43 #### Blink the Caps Lock LED every .5 seconds
  44
  45 ```C
  46 #include "timer.h"
  47 #include "led.h"
  48
  49 bool my_led_status = 0;
  50 uint16_t my_led_timer;
  51
  52 void hook_keyboard_loop(void)
  53 {
  54     // check if we've reached 500 milliseconds yet...
  55     if (timer_elapsed(my_led_timer) > 500)
  56     {
  57         // we've reached 500 milliseconds!
  58         // reset the timer
  59         my_led_timer = timer_read();
  60
  61         // check the current LED state
  62         if (my_led_status)
  63         {
  64             // LED is on, so let's turn it off
  65             led_set(host_keyboard_leds() & ~(1<<USB_LED_CAPS_LOCK));
  66             my_led_status = 0;
  67         }
  68         else
  69         {
  70             // LED is off, so let's turn it on
  71             led_set(host_keyboard_leds() | (1<<USB_LED_CAPS_LOCK));
  72             my_led_status = 1;
  73         }
  74     }
  75 }
  76 ```
  77
  78 #### Flash the Caps Lock LED for 20ms on every keypress
  79 ```C
  80 include "timer.h"
  81 #include "led.h"
  82
  83 bool my_led_status = 0;
  84 uint16_t my_led_timer;
  85
  86 void hook_matrix_change(keyevent_t event)
  87 {
  88     // only flash LED for key press events, not key release events.
  89     if (event.pressed)
  90     {
  91         // check the current LED status and reverse it
  92         led_set(host_keyboard_leds() ^ (1<<USB_LED_CAPS_LOCK));
  93
  94         my_led_status = 1;
  95         my_led_timer = timer_read();
  96     }
  97 }
  98
  99 void hook_keyboard_loop(void)
 100 {
 101     if (my_led_status)
 102     {
 103         // check if we've reached 20 milliseconds yet...
 104         if (timer_elapsed(my_led_timer) > 50)
 105         {
 106             led_set(host_keyboard_leds());
 107
 108             my_led_status = 0;
 109         }
 110     }
 111 }
 112
 113 ```