Merge branch 'newapi' into develop

Author: tmk

common/action_layer.c

@@ -22,6 +22,7 @@ static void default_layer_state_set(uint32_t state)
     debug("default_layer_state: ");
     default_layer_debug(); debug(" to ");
     default_layer_state = state;
+    hook_default_layer_change(default_layer_state);
     default_layer_debug(); debug("\n");
     clear_keyboard_but_mods(); // To avoid stuck keys
 }

common/hook.c

@@ -19,43 +19,31 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include "hook.h"
 
 /* -------------------------------------------------
- * Definitions of hardware-independent default hooks
+ * Definitions of default hooks
  * ------------------------------------------------- */
 
-/* Called on layer state change event. */
-/* Default behaviour: do nothing. */
 __attribute__((weak))
-void hook_layer_change(uint8_t layer_state) {
-    (void)layer_state;
+void hook_keyboard_loop(void) {}
+
+__attribute__((weak))
+void hook_matrix_change(keyevent_t event) {
+    (void)event;
 }
 
-/* Called periodically from the matrix scan loop (very often!) */
-/* Default behaviour: do nothing. */
 __attribute__((weak))
-void hook_keyboard_loop(void) {}
+void hook_default_layer_change(uint8_t layer_state) {
+    (void)layer_state;
+}
 
-/* Called on matrix state change event (every keypress => often!) */
-/* Default behaviour: do nothing. */
 __attribute__((weak))
-void hook_matrix_change(keyevent_t event) {
-	(void)event;
+void hook_layer_change(uint8_t layer_state) {
+    (void)layer_state;
 }
 
-/* Called on indicator LED update event (when reported from host). */
-/* Default behaviour: calls led_set (for compatibility). */
 __attribute__((weak))
 void hook_keyboard_leds_change(uint8_t led_status) {
     keyboard_set_leds(led_status);
 }
 
-/* Called once, on checking the bootmagic combos. */
-/* Default behaviour: do nothing. */
 __attribute__((weak))
-void hook_bootmagic(void) {
-	/* An example: */
-	// #include "bootmagic.h"
-	// #include "keymap.h"
-	// if(bootmagic_scan_keycode(KC_W)) {
-	// 	// do something
-	// }
-}
+void hook_bootmagic(void) {}

common/hook.h

@@ -22,14 +22,14 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include "led.h"
 
 /* -------------------------------------
- *       Hardware / one-off hooks
+ * Protocol hooks
  * ------------------------------------- */
 
-/* Called once, before initialising USB. */
+/* Called once, very early stage of initialization, just after processor startup. */
 /* Default behaviour: do nothing. */
 void hook_early_init(void);
 
-/* Called once, after USB is connected and keyboard initialised. */
+/* Called once, very last stage of initialization, just before keyboard loop. */
 /* Default behaviour: do nothing. */
 void hook_late_init(void);
 
@@ -47,12 +47,9 @@ void hook_usb_suspend_loop(void);
  * the "normal" indicator LED status by default. */
 void hook_usb_wakeup(void);
 
-/* Called once, on checking the bootmagic combos. */
-/* Default behaviour: do nothing. */
-void hook_bootmagic(void);
 
 /* -------------------------------------
- *       Keyboard / periodic hooks
+ * Keyboard hooks
  * ------------------------------------- */
 
 /* Called periodically from the keyboard loop (very often!) */
@@ -63,12 +60,21 @@ void hook_keyboard_loop(void);
 /* Default behaviour: do nothing. */
 void hook_matrix_change(keyevent_t event);
 
+/* Called on default layer state change event. */
+/* Default behaviour: do nothing. */
+void hook_default_layer_change(uint32_t default_layer_state);
+
 /* Called on layer state change event. */
 /* Default behaviour: do nothing. */
-void hook_layer_change(uint8_t layer_state);
+void hook_layer_change(uint32_t layer_state);
 
 /* Called on indicator LED update event (when reported from host). */
-/* Default behaviour: calls keyboard_set_leds (for compatibility). */
+/* Default behaviour: calls keyboard_set_leds. */
 void hook_keyboard_leds_change(uint8_t led_status);
 
+/* Called once, on checking the bootmagic combos. */
+/* Default behaviour: do nothing. */
+void hook_bootmagic(void);
+
+
 #endif /* _HOOKS_H_ */

doc/hook.txt

@@ -0,0 +1,111 @@
+Hooks
+-----
+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.
+
+The following hooks are available available:
+
+Hook function                   | Timing
+--------------------------------|-----------------------------------------------
+`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.
+`hook_late_init(void)`          | Near the end of the boot process, after Boot Magic has run and LEDs have been initialized.
+`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.
+`hook_usb_wakeup(void)`         | When the device wakes up from USB suspend state.
+`hook_usb_suspend_entry(void)`  | When the device enters USB suspend state.
+`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.
+`hook_keyboard_loop(void)`      | Continuously, during the main loop, after the matrix is checked.
+`hook_matrix_change(keyevent_t event)`      | When a matrix state change is detected, before any other actions are processed.
+`hook_layer_change(uint32_t layer_state)`   | When any layer is changed.
+`hook_default_layer_change(uint32_t default_layer_state)`   | When any default layer is changed.
+`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)`
+
+
+
+
+
+### Hooks Examples
+
+You can try these out by copying the code to your keymap file, or any .c file in the Makefile `SRC`.
+
+#### Activate keymap layer 5 on startup
+
+```C
+#include "action_layer.h"
+
+void hook_late_init(void)
+{
+    layer_on(5);
+    print("Layer 5 enabled!");
+}
+```
+
+#### Blink the Caps Lock LED every .5 seconds
+
+```C
+#include "timer.h"
+#include "led.h"
+
+bool my_led_status = 0;
+uint16_t my_led_timer;
+
+void hook_keyboard_loop(void)
+{
+    // check if we've reached 500 milliseconds yet...
+    if (timer_elapsed(my_led_timer) > 500)
+    {
+        // we've reached 500 milliseconds!
+        // reset the timer
+        my_led_timer = timer_read();
+
+        // check the current LED state
+        if (my_led_status)
+        {
+            // LED is on, so let's turn it off
+            led_set(host_keyboard_leds() & ~(1<<USB_LED_CAPS_LOCK));
+            my_led_status = 0;
+        }
+        else
+        {
+            // LED is off, so let's turn it on
+            led_set(host_keyboard_leds() | (1<<USB_LED_CAPS_LOCK));
+            my_led_status = 1;
+        }
+    }
+}
+```
+
+#### Flash the Caps Lock LED for 20ms on every keypress
+```C
+include "timer.h"
+#include "led.h"
+
+bool my_led_status = 0;
+uint16_t my_led_timer;
+
+void hook_matrix_change(keyevent_t event)
+{
+    // only flash LED for key press events, not key release events.
+    if (event.pressed)
+    {
+        // check the current LED status and reverse it
+        led_set(host_keyboard_leds() ^ (1<<USB_LED_CAPS_LOCK));
+
+        my_led_status = 1;
+        my_led_timer = timer_read();
+    }
+}
+
+void hook_keyboard_loop(void)
+{
+    if (my_led_status)
+    {
+        // check if we've reached 20 milliseconds yet...
+        if (timer_elapsed(my_led_timer) > 50)
+        {
+            led_set(host_keyboard_leds());
+
+            my_led_status = 0;
+        }
+    }
+}
+
+```