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

diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index 6d741b6cb251120c9054dfdca39c35a7e17e21b1..9a1c486dfd0728050ddffb9a5fd053cf779496c2 100644 (file)
--- 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)`
 
 * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
 * Keymap: `void led_set_user(uint8_t usb_led)`
 

+

 # Matrix Initialization Code
 
 # 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
 
 
 ### 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.
 
 
 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
 
 # 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
 
 
 ### Example `layer_state_set_*` Implementation
 

diff --git a/tmk_core/common/avr/suspend.c b/tmk_core/common/avr/suspend.c
index 3aa3d124746b32ebafce45aa5065047df43cec9d..dfa1af273c0b238aea6e7fe7933a248b6c67a2f4 100644 (file)
--- 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;
 
  */
 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
 /** \brief Power down
  *
  * FIXME: needs doc


@@ -103,6 +118,8 @@ static void power_down(uint8_t wdto)
 #endif
   rgblight_disable_noeeprom();
 #endif
 #endif
   rgblight_disable_noeeprom();
 #endif

+  suspend_power_down_kb();
+

     // TODO: more power saving
     // See PicoPower application note
     // - I/O port input with pullup
     // 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;
 }
 
      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
 /** \brief run immediately after wakeup
  *
  * FIXME: needs doc


@@ -162,6 +194,7 @@ void suspend_wakeup_init(void)
   rgblight_timer_enable();
 #endif
 #endif
   rgblight_timer_enable();
 #endif
 #endif

+  suspend_wakeup_init_kb();

 }
 
 #ifndef NO_SUSPEND_POWER_DOWN
 }
 
 #ifndef NO_SUSPEND_POWER_DOWN

diff --git a/tmk_core/common/chibios/suspend.c b/tmk_core/common/chibios/suspend.c
index 32ef773e2e4507f0b2a98c95a86abda6b27c3d0c..4a119ccefee60d7e02280d026826953d27814227 100644 (file)
--- 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);
 }
 
        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
 /** \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
 
        // 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
 
        // 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;
 }
 
     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
 /** \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 */
 #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 80617a824447db8ec709e9c0062d9bd6fe8955a1..c3e4447085c239d55d4cf13c2dc0eba317103ab5 100644 (file)
--- 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);
 
 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
 #endif