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@2:c8a0c0e328db, 2017-04-10 (annotated)

Committer:
RobMeades
Date:
Mon Apr 10 11:50:47 2017 +0000
Revision:
2:c8a0c0e328db
Parent:
1:4f2c412dc013
Child:
3:442c9afc0229
Move the BACKUP_SRAM macro into the class as the Doxygen documentation generator in the mbed IDE doesn't pick it up otherwise.

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