tmk_core/doc/hook.txt

   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 `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 `hook_late_init(void)`          | Near the end of the boot process, after Boot Magic has run and LEDs have been initialized.
  11 `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 `hook_usb_wakeup(void)`         | When the device wakes up from USB suspend state.
  13 `hook_usb_suspend_entry(void)`  | When the device enters USB suspend state.
  14 `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.
  15 `hook_keyboard_loop(void)`      | Continuously, during the main loop, after the matrix is checked.
  16 `hook_matrix_change(keyevent_t event)`      | When a matrix state change is detected, before any other actions are processed.
  17 `hook_layer_change(uint32_t layer_state)`   | When any layer is changed.
  18 `hook_default_layer_change(uint32_t default_layer_state)`   | When any default layer is changed.
  19 `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)`
  20
  21
  22
  23
  24
  25 ### Hooks Examples
  26
  27 You can try these out by copying the code to your keymap file, or any .c file in the Makefile `SRC`.
  28
  29 #### Activate keymap layer 5 on startup
  30
  31 ```C
  32 #include "action_layer.h"
  33
  34 void hook_late_init(void)
  35 {
  36     layer_on(5);
  37     print("Layer 5 enabled!");
  38 }
  39 ```
  40
  41 #### Blink the Caps Lock LED every .5 seconds
  42
  43 ```C
  44 #include "timer.h"
  45 #include "led.h"
  46
  47 bool my_led_status = 0;
  48 uint16_t my_led_timer;
  49
  50 void hook_keyboard_loop(void)
  51 {
  52     // check if we've reached 500 milliseconds yet...
  53     if (timer_elapsed(my_led_timer) > 500)
  54     {
  55         // we've reached 500 milliseconds!
  56         // reset the timer
  57         my_led_timer = timer_read();
  58
  59         // check the current LED state
  60         if (my_led_status)
  61         {
  62             // LED is on, so let's turn it off
  63             led_set(host_keyboard_leds() & ~(1<<USB_LED_CAPS_LOCK));
  64             my_led_status = 0;
  65         }
  66         else
  67         {
  68             // LED is off, so let's turn it on
  69             led_set(host_keyboard_leds() | (1<<USB_LED_CAPS_LOCK));
  70             my_led_status = 1;
  71         }
  72     }
  73 }
  74 ```
  75
  76 #### Flash the Caps Lock LED for 20ms on every keypress
  77 ```C
  78 include "timer.h"
  79 #include "led.h"
  80
  81 bool my_led_status = 0;
  82 uint16_t my_led_timer;
  83
  84 void hook_matrix_change(keyevent_t event)
  85 {
  86     // only flash LED for key press events, not key release events.
  87     if (event.pressed)
  88     {
  89         // check the current LED status and reverse it
  90         led_set(host_keyboard_leds() ^ (1<<USB_LED_CAPS_LOCK));
  91
  92         my_led_status = 1;
  93         my_led_timer = timer_read();
  94     }
  95 }
  96
  97 void hook_keyboard_loop(void)
  98 {
  99     if (my_led_status)
 100     {
 101         // check if we've reached 20 milliseconds yet...
 102         if (timer_elapsed(my_led_timer) > 50)
 103         {
 104             led_set(host_keyboard_leds());
 105
 106             my_led_status = 0;
 107         }
 108     }
 109 }
 110
 111 ```