Squashed 'tmk_core/' changes from d5c5ac6..8da1898
[tmk_keyboard.git] / 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 ```
Imprint / Impressum