u-blox / low-power-sleep

This class provides an API to assist with low power behaviour on an STM32F437 micro, as used on the u-blox C030 board. If you need to operate from battery for any significant period, or are mains powered and don't want to take the planet down with you, you should design your code with this in mind. This library uses the https://developer.mbed.org/users/Sissors/code/WakeUp/ library and so could be extended to support all of the MCUs that library supports.

Dependencies:   WakeUp

Dependents:   example-low-power-sleep aconnoCellularGnss

low_power.h@4:691e6b38fc54, 2017-06-05 (annotated)

Committer:
RobMeades
Date:
Mon Jun 05 14:28:14 2017 +0000
Revision:
4:691e6b38fc54
Parent:
3:442c9afc0229 
Update readme.txt.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rob.meades@u-blox.com 1:4f2c412dc013 1 /* mbed Microcontroller Library
rob.meades@u-blox.com 1:4f2c412dc013 2 * Copyright (c) 2017 u-blox
rob.meades@u-blox.com 1:4f2c412dc013 3 *
rob.meades@u-blox.com 1:4f2c412dc013 4 * Licensed under the Apache License, Version 2.0 (the "License");
rob.meades@u-blox.com 1:4f2c412dc013 5 * you may not use this file except in compliance with the License.
rob.meades@u-blox.com 1:4f2c412dc013 6 * You may obtain a copy of the License at
rob.meades@u-blox.com 1:4f2c412dc013 7 *
rob.meades@u-blox.com 1:4f2c412dc013 8 * http://www.apache.org/licenses/LICENSE-2.0
rob.meades@u-blox.com 1:4f2c412dc013 9 *
rob.meades@u-blox.com 1:4f2c412dc013 10 * Unless required by applicable law or agreed to in writing, software
rob.meades@u-blox.com 1:4f2c412dc013 11 * distributed under the License is distributed on an "AS IS" BASIS,
rob.meades@u-blox.com 1:4f2c412dc013 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rob.meades@u-blox.com 1:4f2c412dc013 13 * See the License for the specific language governing permissions and
rob.meades@u-blox.com 1:4f2c412dc013 14 * limitations under the License.
rob.meades@u-blox.com 1:4f2c412dc013 15 */
rob.meades@u-blox.com 1:4f2c412dc013 16
rob.meades@u-blox.com 1:4f2c412dc013 17 #ifndef LOW_POWER_H
rob.meades@u-blox.com 1:4f2c412dc013 18 #define LOW_POWER_H
rob.meades@u-blox.com 1:4f2c412dc013 19
rob.meades@u-blox.com 1:4f2c412dc013 20 #include <WakeUp.h>
rob.meades@u-blox.com 1:4f2c412dc013 21
rob.meades@u-blox.com 1:4f2c412dc013 22 /**
rob.meades@u-blox.com 1:4f2c412dc013 23 * @file low_power.h
rob.meades@u-blox.com 1:4f2c412dc013 24 * This file defines a class intended to assist with obtaining lowest power
rob.meades@u-blox.com 1:4f2c412dc013 25 * operation on an STM32F437 microprocessor.
rob.meades@u-blox.com 1:4f2c412dc013 26 */
rob.meades@u-blox.com 1:4f2c412dc013 27
RobMeades 3:442c9afc0229 28 /* ----------------------------------------------------------------
RobMeades 3:442c9afc0229 29 * COMPILE-TIME MACROS
RobMeades 3:442c9afc0229 30 * -------------------------------------------------------------- */
rob.meades@u-blox.com 1:4f2c412dc013 31
RobMeades 3:442c9afc0229 32 /* ----------------------------------------------------------------
RobMeades 3:442c9afc0229 33 * CLASSES
RobMeades 3:442c9afc0229 34 * -------------------------------------------------------------- */
rob.meades@u-blox.com 1:4f2c412dc013 35
RobMeades 3:442c9afc0229 36 /** Low power library.
RobMeades 3:442c9afc0229 37 * Note: as it handles a hardware resource, there can only be one
RobMeades 3:442c9afc0229 38 * instance of this class; it is best to instantiate it statically
RobMeades 3:442c9afc0229 39 * at the top of your code or it can be instantiated once at the
RobMeades 3:442c9afc0229 40 * top of main().
RobMeades 3:442c9afc0229 41 */
rob.meades@u-blox.com 1:4f2c412dc013 42 class LowPower: public WakeUp {
rob.meades@u-blox.com 1:4f2c412dc013 43 public:
rob.meades@u-blox.com 1:4f2c412dc013 44
RobMeades 3:442c9afc0229 45 /** Size of backup SRAM. */
RobMeades 3:442c9afc0229 46 #ifdef TARGET_STM
RobMeades 3:442c9afc0229 47 # define BACKUP_SRAM_SIZE 4096
RobMeades 3:442c9afc0229 48 #else
RobMeades 3:442c9afc0229 49 # define BACKUP_SRAM_SIZE 0
RobMeades 3:442c9afc0229 50 #endif
RobMeades 2:c8a0c0e328db 51
RobMeades 3:442c9afc0229 52 /** Macro to force a variable into backup SRAM.
RobMeades 3:442c9afc0229 53 * Place this on the line preceding the declaration of a variable
RobMeades 3:442c9afc0229 54 * if that variable must be retained when the processor is in Standby
RobMeades 3:442c9afc0229 55 * mode. For example:
RobMeades 3:442c9afc0229 56 *
RobMeades 3:442c9afc0229 57 * BACKUP_SRAM
RobMeades 3:442c9afc0229 58 * uint32_t importantThing;
RobMeades 3:442c9afc0229 59 *
RobMeades 3:442c9afc0229 60 * Note that variables marked in this way cannot be statically
RobMeades 3:442c9afc0229 61 * initialised, their initial values at cold-start will always be zero,
RobMeades 3:442c9afc0229 62 * i.e. even with the following declaration importantThing will
RobMeades 3:442c9afc0229 63 * have a value of 0 when it is first accessed:
RobMeades 3:442c9afc0229 64 *
RobMeades 3:442c9afc0229 65 * BACKUP_SRAM
RobMeades 3:442c9afc0229 66 * uint32_t importantThing = 3;
RobMeades 3:442c9afc0229 67 */
RobMeades 3:442c9afc0229 68 # define BACKUP_SRAM __attribute__ ((section ("BKPSRAM")))
RobMeades 3:442c9afc0229 69
RobMeades 3:442c9afc0229 70 /** Constructor. */
rob.meades@u-blox.com 1:4f2c412dc013 71 LowPower(void);
RobMeades 3:442c9afc0229 72 /** Destructor. */
rob.meades@u-blox.com 1:4f2c412dc013 73 ~LowPower(void);
rob.meades@u-blox.com 1:4f2c412dc013 74
RobMeades 3:442c9afc0229 75 /** Exit debug mode.
RobMeades 3:442c9afc0229 76 * On a standard mbed board the host microcontroller is held
RobMeades 3:442c9afc0229 77 * in debug mode by the debug chip on the board. When the
RobMeades 3:442c9afc0229 78 * host microcontroller is in debug mode it cannot enter Standby
RobMeades 3:442c9afc0229 79 * mode normally. So to be able to use Standby mode, you
RobMeades 3:442c9afc0229 80 * must call this as the VERY FIRST THING you do on entry
RobMeades 3:442c9afc0229 81 * to main(); it will perform a soft reset of the microcontroller
RobMeades 3:442c9afc0229 82 * to cut the debug mode connection with the debug chip.
RobMeades 3:442c9afc0229 83 */
rob.meades@u-blox.com 1:4f2c412dc013 84 void exitDebugMode(void);
rob.meades@u-blox.com 1:4f2c412dc013 85
RobMeades 3:442c9afc0229 86 /** Enter Stop mode.
RobMeades 3:442c9afc0229 87 * @param stopPeriodMilliseconds the amount of time to remain in Stop
RobMeades 3:442c9afc0229 88 * mode for. When the time has expired the function
RobMeades 3:442c9afc0229 89 * will return. The maximum delay is one calender month.
RobMeades 3:442c9afc0229 90 * It is up to the caller to ensure that the requested
RobMeades 3:442c9afc0229 91 * sleep time does not overflow the number of days in the
RobMeades 3:442c9afc0229 92 * current calender month. This function will disable the RTOS
RobMeades 3:442c9afc0229 93 * tick and so any RTOS timers will be frozen for the duration of
RobMeades 3:442c9afc0229 94 * Stop mode; they will not tick and will not expire during this
RobMeades 3:442c9afc0229 95 * time. Any other enabled interrupts can bring the processor out of
RobMeades 3:442c9afc0229 96 * Stop mode.
RobMeades 3:442c9afc0229 97 * Note: during Stop mode the processor is running from a 32 kHz
RobMeades 3:442c9afc0229 98 * clock and so any interrupt that is triggered will run
RobMeades 3:442c9afc0229 99 * correspondingly slower.
RobMeades 3:442c9afc0229 100 * Note: if the watchdog is being used, the caller should set the
RobMeades 3:442c9afc0229 101 * watchdog timeout to longer period than the Stop period.
RobMeades 3:442c9afc0229 102 */
rob.meades@u-blox.com 1:4f2c412dc013 103 void enterStop(uint32_t stopPeriodMilliseconds);
rob.meades@u-blox.com 1:4f2c412dc013 104
rob.meades@u-blox.com 1:4f2c412dc013 105
RobMeades 3:442c9afc0229 106 /** Enter Standby mode. Note that this function does NOT return. Or
RobMeades 3:442c9afc0229 107 * rather, if this function returns, there has been an error.
RobMeades 3:442c9afc0229 108 * @param standbyPeriodMilliseconds the amount of time to remain in Standby
RobMeades 3:442c9afc0229 109 * mode for. When the time has expired the processor will
RobMeades 3:442c9afc0229 110 * be reset and begin execution once more from main(). The
RobMeades 3:442c9afc0229 111 * values stored in BACKUP_SRAM will be retained, all other
RobMeades 3:442c9afc0229 112 * variables will be reset to their initial state. The RTOS
RobMeades 3:442c9afc0229 113 * is suspended on entry to Standby mode (i.e. no RTOS timers
RobMeades 3:442c9afc0229 114 * will run) and the RTOS will be reset on return to main().
RobMeades 3:442c9afc0229 115 * The maximum delay is one calender month.
RobMeades 3:442c9afc0229 116 * It is up to the caller to ensure that the requested
RobMeades 3:442c9afc0229 117 * sleep time does not overflow the number of days in the
RobMeades 3:442c9afc0229 118 * current calender month.
RobMeades 3:442c9afc0229 119 * Note: Standby mode will only work on a standard mbed board
RobMeades 3:442c9afc0229 120 * if exitDebugMode has previously been called.
RobMeades 3:442c9afc0229 121 * Note: any enabled external interrupt can wake the processor from
RobMeades 3:442c9afc0229 122 * Standby mode, just as if the end of the period has expired.
RobMeades 3:442c9afc0229 123 * Note: if the watchdog is being used, the caller should set the
RobMeades 3:442c9afc0229 124 * watchdog timeout to longer period than the Standby period.
RobMeades 3:442c9afc0229 125 * @param powerDownBackupSram if true, backup SRAM will also be powered
RobMeades 3:442c9afc0229 126 * down in standby mode, otherwise it will be retained.
RobMeades 3:442c9afc0229 127 */
rob.meades@u-blox.com 1:4f2c412dc013 128 void enterStandby(uint32_t standbyPeriodMilliseconds, bool powerDownBackupSram = false);
rob.meades@u-blox.com 1:4f2c412dc013 129
RobMeades 3:442c9afc0229 130 /** Get the number of user interrupts that are enabled, sometimes helpful when debugging
RobMeades 3:442c9afc0229 131 * power-down modes. User interrupts start at 0 and the number of them varies
RobMeades 3:442c9afc0229 132 * with the microcontroller.
RobMeades 3:442c9afc0229 133 * @param pList a pointer to an area in which the list of enabled user interrupts
RobMeades 3:442c9afc0229 134 * will be stored.
RobMeades 3:442c9afc0229 135 * @param sizeOfList the size of the memory pointer to be pList, in bytes.
RobMeades 3:442c9afc0229 136 * @return the number of enabled user interrupts.
RobMeades 3:442c9afc0229 137 */
rob.meades@u-blox.com 1:4f2c412dc013 138 int32_t numUserInterruptsEnabled(uint8_t *pList = NULL, uint32_t sizeOfList = 0);
rob.meades@u-blox.com 1:4f2c412dc013 139
rob.meades@u-blox.com 1:4f2c412dc013 140 protected:
rob.meades@u-blox.com 1:4f2c412dc013 141
RobMeades 3:442c9afc0229 142 /** Check whether an interrupt is enabled or not. */
rob.meades@u-blox.com 1:4f2c412dc013 143 inline uint32_t myNVIC_GetEnableIRQ(IRQn_Type IRQn);
rob.meades@u-blox.com 1:4f2c412dc013 144 };
rob.meades@u-blox.com 1:4f2c412dc013 145
rob.meades@u-blox.com 1:4f2c412dc013 146 #endif
rob.meades@u-blox.com 1:4f2c412dc013 147
RobMeades 3:442c9afc0229 148 /* End Of File */