From cb91320d6d8836dd13db19bd2434abe2e7cadc20 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sun, 3 Jun 2018 14:57:35 -0700 Subject: [PATCH] Add Suspend functions (#3112) * Add suspend functions * Disable RGB code if it's disabled * Add suspend code to ChibiOS for future compatibility * Add keyboard_init functions * Change where references so it will compile * Wrong command chained in wake up kb function * Fix non-feature file changes * Add documentation * Re-add matrix init docs * add rgblight code to example * Remove keyboard init stuff for separate PR --- docs/custom_quantum_functions.md | 35 +++++++++++++++++++++++++++++-- tmk_core/common/avr/suspend.c | 33 +++++++++++++++++++++++++++++ tmk_core/common/chibios/suspend.c | 33 +++++++++++++++++++++++++++++ tmk_core/common/suspend.h | 5 +++++ 4 files changed, 104 insertions(+), 2 deletions(-) diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 6d741b6cb2..9a1c486dfd 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -135,9 +135,11 @@ void led_set_user(uint8_t usb_led) { * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)` * Keymap: `void led_set_user(uint8_t usb_led)` + # Matrix Initialization Code -Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used. +Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used. + ### Example `matrix_init_user()` Implementation @@ -177,9 +179,38 @@ This function gets called at every matrix scan, which is basically as often as t You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing. +# Keyboard Idling/Wake Code + +If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard. + +This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively. + + +### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation + +This example, at the keyboard level, sets up B1, B2, and B3 as LED pins. + +``` +void suspend_power_down_user(void) +{ + rgb_matrix_set_suspend_state(true); +} + +void suspend_wakeup_init_user(void) +{ + rgb_matrix_set_suspend_state(false); +} + +``` + +### `keyboard_init_*` Function Documentation + +* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` +* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` + # Layer Change Code -Thir runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. +This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. ### Example `layer_state_set_*` Implementation diff --git a/tmk_core/common/avr/suspend.c b/tmk_core/common/avr/suspend.c index 3aa3d12474..dfa1af273c 100644 --- a/tmk_core/common/avr/suspend.c +++ b/tmk_core/common/avr/suspend.c @@ -72,6 +72,21 @@ void suspend_idle(uint8_t time) */ static uint8_t wdt_timeout = 0; +/** \brief Run keyboard level Power down + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_power_down_user (void) { } +/** \brief Run keyboard level Power down + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_power_down_kb(void) { + suspend_power_down_user(); +} + /** \brief Power down * * FIXME: needs doc @@ -103,6 +118,8 @@ static void power_down(uint8_t wdto) #endif rgblight_disable_noeeprom(); #endif + suspend_power_down_kb(); + // TODO: more power saving // See PicoPower application note // - I/O port input with pullup @@ -144,6 +161,21 @@ bool suspend_wakeup_condition(void) return false; } +/** \brief run user level code immediately after wakeup + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_wakeup_init_user(void) { } + +/** \brief run keyboard level code immediately after wakeup + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_wakeup_init_kb(void) { + suspend_wakeup_init_user(); +} /** \brief run immediately after wakeup * * FIXME: needs doc @@ -162,6 +194,7 @@ void suspend_wakeup_init(void) rgblight_timer_enable(); #endif #endif + suspend_wakeup_init_kb(); } #ifndef NO_SUSPEND_POWER_DOWN diff --git a/tmk_core/common/chibios/suspend.c b/tmk_core/common/chibios/suspend.c index 32ef773e2e..4a119ccefe 100644 --- a/tmk_core/common/chibios/suspend.c +++ b/tmk_core/common/chibios/suspend.c @@ -21,6 +21,21 @@ void suspend_idle(uint8_t time) { wait_ms(time); } +/** \brief Run keyboard level Power down + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_power_down_user (void) { } +/** \brief Run keyboard level Power down + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_power_down_kb(void) { + suspend_power_down_user(); +} + /** \brief suspend power down * * FIXME: needs doc @@ -30,6 +45,7 @@ void suspend_power_down(void) { // shouldn't power down TPM/FTM if we want a breathing LED // also shouldn't power down USB + suspend_power_down_kb(); // on AVR, this enables the watchdog for 15ms (max), and goes to // SLEEP_MODE_PWR_DOWN @@ -53,6 +69,22 @@ bool suspend_wakeup_condition(void) return false; } +/** \brief run user level code immediately after wakeup + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_wakeup_init_user(void) { } + +/** \brief run keyboard level code immediately after wakeup + * + * FIXME: needs doc + */ +__attribute__ ((weak)) +void suspend_wakeup_init_kb(void) { + suspend_power_down_user(); +} + /** \brief suspend wakeup condition * * run immediately after wakeup @@ -79,4 +111,5 @@ void suspend_wakeup_init(void) #ifdef BACKLIGHT_ENABLE backlight_init(); #endif /* BACKLIGHT_ENABLE */ + suspend_wakeup_init_kb(); } diff --git a/tmk_core/common/suspend.h b/tmk_core/common/suspend.h index 80617a8244..c3e4447085 100644 --- a/tmk_core/common/suspend.h +++ b/tmk_core/common/suspend.h @@ -10,4 +10,9 @@ void suspend_power_down(void); bool suspend_wakeup_condition(void); void suspend_wakeup_init(void); +void suspend_wakeup_init_user(void); +void suspend_wakeup_init_kb(void); +void suspend_power_down_user (void); +void suspend_power_down_kb(void); + #endif