refactor: break out different areas of functionality

1 files changed, 105 insertions, 0 deletions

diff --git a/watch-library/watch/watch_app.h b/watch-library/watch/watch_app.h
new file mode 100644
index 00000000..fd7ea706
--- /dev/null
+++ b/watch-library/watch/watch_app.h
@@ -0,0 +1,105 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2020 Joey Castillo
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+////< @file watch_app.h
+
+/** @addtogroup app Application Framework
+  * @brief This section covers the functions that you will implement in your app.c file when designing a Sensor Watch app.
+  * @details You should be able to write a watch app by simply implementing these functions and declaring callbacks for
+  *          various GPIO and peripheral interrupts. The main.c file takes care of calling these functions for you. The
+  *          general flow:
+  *
+  *            1. Your app_init() function is called.
+  *               - This method should only be used to set your initial application state.
+  *            2. If your app is waking from BACKUP, app_wake_from_deep_sleep()  is called.
+  *               - If you saved state in the RTC's backup registers, you can restore it here.
+  *            3. Your app_setup() method is called.
+  *               - You may wish to enable some functionality and peripherals here.
+  *               - You should definitely set up some interrupts here.
+  *            4. The main run loop begins: your app_loop() function is called.
+  *               - Run code and update your UI here.
+  *               - Return true if your app is prepared to enter STANDBY mode.
+  *            5. This step differs depending on the value returned by app_loop:
+  *               - If you returned false, execution resumes at (4).
+  *               - If you returned true, app_prepare_for_sleep() is called; execution moves on to (6).
+  *            6. The microcontroller enters the STANDBY sleep mode.
+  *               - No user code will run, and the watch will enter a low power mode.
+  *               - The watch will remain in this state until an interrupt wakes it.
+  *            7. Once woken from STANDBY, your app_wake_from_sleep() function is called.
+  *               - After this, execution resumes at (4).
+  */
+/// @{
+/** @brief A function you will implement to initialize your application state. The app_init function is called before
+  *        anything else. Use it to set up any internal data structures or application state required by your app,
+  *        but don't configure any peripherals just yet.
+  */
+void app_init();
+
+/** @brief A function you will implement to wake from deep sleep mode. The app_wake_from_deep_sleep function is only
+  *        called if your app is waking from the ultra-low power BACKUP sleep mode. You may have chosen to store some
+  *        state in the RTC's backup registers prior to entering this mode. You may restore that state here.
+  */
+void app_wake_from_deep_sleep();
+
+/** @brief A function you will implement to set up your application. The app_setup function is like setup() in Arduino.
+  *        It is called once when the program begins. You should set pin modes and enable any peripherals you want to
+  *        set up (real-time clock, I2C, etc.) Depending on your application, you may or may not want to configure
+  *        sensors on your sensor board here. For example, a low-power accelerometer that will run at all times should
+  *        be configured here, whereas you may want to enable a more power-hungry sensor only when you need it.
+  * @note If your app enters the ultra-low power BACKUP sleep mode, this function will be called again when it wakes
+  *       from that deep sleep state. In this state, the RTC will still be configured with the correct date and time.
+  */
+void app_setup();
+
+/** @brief A function you will implement to serve as the app's main run loop. This method will be called repeatedly,
+           or if you enter STANDBY sleep mode, as soon as the device wakes from sleep.
+  * @return You should return true if your app is prepared to enter STANDBY sleep mode. If you return false, your
+  *         app's app_loop method will be called again immediately. Note that in STANDBY mode, the watch will consume
+  *         only about 95 microamperes of power, whereas if you return false and keep the app awake, it will consume
+  *         about 355 microamperes. This is the difference between months of battery life and days. As much as
+  *         possible, you should limit the amount of time your app spends awake.
+  * @note Only the RTC, the segment LCD controller and the external interrupt controller run in STANDBY mode. If you
+  *       are using, e.g. the PWM function to set a custom LED color, you should return false here until you are
+  *       finished with that operation. Note however that the peripherals will continue running after waking up,
+  *       so e.g. the I2C controller, if configured, will sleep in STANDBY. But you can use it again as soon as your
+  *       app wakes up.
+  */
+bool app_loop();
+
+/** @brief A function you will implement to prepare to enter STANDBY sleep mode. The app_prepare_for_sleep function is
+ *         called before the watch goes into the STANDBY sleep mode. In STANDBY mode, most peripherals are shut down,
+ *         and no code will run until the watch receives an interrupt (generally either the 1Hz tick or a press on one
+ *         of the buttons).
+ * @note If you are PWM'ing the LED or playing a sound on the buzzer, the TC/TCC peripherals that drive those operations
+ *       will not run in STANDBY. BUT! the output pins will retain the state they had when entering standby. This means
+ *       you could end up entering standby with an LED on and draining power, or with a DC potential across the piezo
+ *       buzzer that could damage it if left in this state. If your app_loop does not prevent sleep during these
+ *       activities, you should make sure to disable these outputs in app_prepare_for_sleep.
+ */
+void app_prepare_for_sleep();
+
+/** @brief A method you will implement to configure the app after waking from STANDBY sleep mode.
+  */
+void app_wake_from_sleep();
+
+/// @}