2.6 Power Driver
2.6.1 Introduction
The MPLAB® Code Configurator (MCC) Melody Power Driver generates APIs to support power-saving modes and functionality on supported MCUs. These modes provide a variety of options for selective power conservation in applications where resources may be limited. This module generates APIs to access power saving features across PIC and AVR devices.
2.6.2 Supported Devices
All supported 8-bit PIC Devices | All supported 8-bit AVR Devices |
2.6.3 Required header files
#include "mcc_generated_files/power/power.h"
2.6.4 How to use the Power Driver
The Power driver generates a portable API interface. For an example of how to use the interface, refer to this example linked below. Click the link to view the code snippets associated with the example:
- Power Driver Use Case 1: Sleep on Switch press This example sets up a project which disables TMR1 peripheral and executes Idle Sleep funtionality when Switch 1 is pressed and wakes up again after 1s. When Switch 2 is pressed, it enables the TMR1 peripheral again and starts toggling.
2.6.5 Module Documentation
2.6.5.1 POWER
This is the generated header file for the POWER driver.
2.6.5.1.1 Module description
This is the generated header file for the POWER driver.
Enumerations
enum power_mode_t { POWER_NORMAL_MODE = 8, POWER_DOZE_MODE = 9, POWER_SLEEP_MODE = 10, POWER_IDLE_MODE = 11 }
Contains the available power modes.
enum power_doze_t { POWER_1_2 = 0, POWER_1_4 = 1, POWER_1_8 = 2, POWER_1_16 = 3, POWER_1_32 = 4, POWER_1_64 = 5, POWER_1_128 = 6, POWER_1_256 = 7 }
Contains the available doze ratio.
enum power_peripheral_t { POWER_IOC = 0x0001, POWER_CLKR = 0x0002, POWER_SCAN = 0x0008, POWER_CRC = 0x0010, POWER_HLVD = 0x0020, POWER_FVR = 0x0040, POWER_SYSC = 0x0080, POWER_TMR0 = 0x0101, POWER_TMR1 = 0x0102, POWER_TMR2 = 0x0104, POWER_TMR3 = 0x0108, POWER_TMR4 = 0x0110, POWER_TMR5 = 0x0120, POWER_TMR6 = 0x0140, POWER_SMT1 = 0x0180, POWER_ZCD = 0x0301, POWER_CM1 = 0x0302, POWER_CM2 = 0x0304, POWER_ACT = 0x0380, POWER_ADC = 0x0320, POWER_DAC1 = 0x0340, POWER_NCO1 = 0x0401, POWER_NCO2 = 0x0402, POWER_NCO3 = 0x0404, POWER_DSM1 = 0x0408, POWER_CWG1 = 0x0410, POWER_CWG2 = 0x0420, POWER_CWG3 = 0x0440, POWER_CCP1 = 0x0501, POWER_CCP2 = 0x0502, POWER_CCP3 = 0x0504, POWER_PWM1 = 0x0510, POWER_PWM2 = 0x0520, POWER_PWM3 = 0x0540, POWER_U1 = 0x0608, POWER_U2 = 0x0610, POWER_U3 = 0x0620, POWER_U4 = 0x0640, POWER_U5 = 0x0680, POWER_SPI1 = 0x0602, POWER_SPI2 = 0x0604, POWER_I2C1 = 0x0601, POWER_CLC1 = 0x0701, POWER_CLC2 = 0x0702, POWER_CLC3 = 0x0704, POWER_CLC4 = 0x0708, POWER_CLC5 = 0x0710, POWER_CLC6 = 0x0720, POWER_CLC7 = 0x0740, POWER_CLC8 = 0x0780, POWER_DMA1 = 0x0801, POWER_DMA2 = 0x0802, POWER_DMA6 = 0x0820, POWER_DMA3 = 0x0804, POWER_DMA4 = 0x0808, POWER_DMA5 = 0x0810 }
Contains a list of all the PLIBs available for Peripheral Module Disable (PMD).
Functions
bool POWER_LowPowerModeEnter (power_mode_t powerMode)
Enters and sets the mode in the Power module and puts the device to sleep, depending on the enum entered.
void POWER_SetDozeRatio (power_doze_t ratio)
Sets the doze ratio in the Power module depending on the enum entered.
void POWER_DozeOnExit (bool enable)
Gets true or false boolean data in Power module.
void POWER_RecoverOnInterrupt (bool enable)
Expects true or false boolean data in Power module.
bool POWER_PeripheralEnable (power_peripheral_t peripheral)
This routine enables the Peripheral depending on the enum entered.
bool POWER_PeripheralDisable (power_peripheral_t peripheral)
This routine disables the Peripheral depending on the enum entered.
void POWER_PeripheralDisableAll (void)
Disables all the Peripherals to save power.
2.6.5.1.2 Function Documentation
POWER_DozeOnExit()
void POWER_DozeOnExit (bool enable)
Gets true or false boolean data in Power module.
enable |
Sets/Clears Doze on Exit |
None. |
POWER_LowPowerModeEnter()
bool POWER_LowPowerModeEnter (power_mode_t powerMode)
Enters and sets the mode in the Power module and puts the device to sleep, depending on the enum entered.
Section: POWER APIs
powerMode |
Enters different power modes, specified by an enum of the type power_mode_t. |
True |
Enum is invalid |
False |
Enum is valid |
Section: POWER APIs
POWER_PeripheralDisable()
bool POWER_PeripheralDisable (power_peripheral_t peripheral)
This routine disables the Peripheral depending on the enum entered.
peripheral |
disable, specified as an enum of the type power_peripheral_t. |
True |
Enum is invalid |
False |
Enum is valid |
POWER_PeripheralDisableAll()
void POWER_PeripheralDisableAll (void )
Disables all the Peripherals to save power.
None. |
None. |
POWER_PeripheralEnable()
bool POWER_PeripheralEnable (power_peripheral_t peripheral)
This routine enables the Peripheral depending on the enum entered.
peripheral |
enable, specified as an enum of the type power_peripheral_t. |
True |
Enum is invalid |
False |
Enum is valid |
POWER_RecoverOnInterrupt()
void POWER_RecoverOnInterrupt (bool enable)
Expects true or false boolean data in Power module.
enable |
Sets/Clears Recover-on-Interrupt |
None. |
POWER_SetDozeRatio()
void POWER_SetDozeRatio (power_doze_t ratio)
Sets the doze ratio in the Power module depending on the enum entered.
ratio |
enter different doze ratios, specified as an enum of the type power_doze_t. |
None. |
2.6.5.1.3 Enumeration Type Documentation
power_doze_t
enum power_doze_t
Contains the available doze ratio.
POWER_1_2 | |
POWER_1_4 |
Doze Ratio: 1:2 |
POWER_1_8 |
Doze Ratio: 1:4 |
POWER_1_16 |
Doze Ratio: 1:8 |
POWER_1_32 |
Doze Ratio: 1:16 |
POWER_1_64 |
Doze Ratio: 1:32 |
POWER_1_128 |
Doze Ratio: 1:64 |
POWER_1_256 |
Doze Ratio: 1:128 |
power_mode_t
enum power_mode_t
Contains the available power modes.
Section: Included Files Section: POWER Enumerations
POWER_NORMAL_MODE | |
POWER_DOZE_MODE |
Sleep mode: Normal |
POWER_SLEEP_MODE |
Sleep mode: Doze |
POWER_IDLE_MODE |
Sleep mode: Sleep |
power_peripheral_t
enum power_peripheral_t
Contains a list of all the PLIBs available for Peripheral Module Disable (PMD).
POWER_IOC | |
POWER_CLKR | |
POWER_SCAN | |
POWER_CRC | |
POWER_HLVD | |
POWER_FVR | |
POWER_SYSC | |
POWER_TMR0 | |
POWER_TMR1 | |
POWER_TMR2 | |
POWER_TMR3 | |
POWER_TMR4 | |
POWER_TMR5 | |
POWER_TMR6 | |
POWER_SMT1 | |
POWER_ZCD | |
POWER_CM1 | |
POWER_CM2 | |
POWER_ACT | |
POWER_ADC | |
POWER_DAC1 | |
POWER_NCO1 | |
POWER_NCO2 | |
POWER_NCO3 | |
POWER_DSM1 | |
POWER_CWG1 | |
POWER_CWG2 | |
POWER_CWG3 | |
POWER_CCP1 | |
POWER_CCP2 | |
POWER_CCP3 | |
POWER_PWM1 | |
POWER_PWM2 | |
POWER_PWM3 | |
POWER_U1 | |
POWER_U2 | |
POWER_U3 | |
POWER_U4 | |
POWER_U5 | |
POWER_SPI1 | |
POWER_SPI2 | |
POWER_I2C1 | |
POWER_CLC1 | |
POWER_CLC2 | |
POWER_CLC3 | |
POWER_CLC4 | |
POWER_CLC5 | |
POWER_CLC6 | |
POWER_CLC7 | |
POWER_CLC8 | |
POWER_DMA1 | |
POWER_DMA2 | |
POWER_DMA6 | |
POWER_DMA3 | |
POWER_DMA4 | |
POWER_DMA5 |
2.6.6 Power Example
This section explains use case example of the Power Driver within an MPLAB® Code Configurator (MCC) Melody Project. The purpose of the Power-Saving modes is to reduce power consumption. These modes provide a variety of options for selective power conservation in applications where resources may be limited.
2.6.6.1 Power Driver Examples
2.6.6.1.1 Example of API use case in Power-driver utilizing two switches
This use case sets up a project which disables TMR1 peripheral and executes Idle Sleep funtionality, when a switch 1 is pressed. and wakes up on the interrupt of TMR0 after 1s. on the switch press 2, it enables the TMR1 peripheral and starts toggling.
-
System>Clock Control:
-
Clock Source: FOSC (1MHz_HFINTOSC/16)
-
-
System>Pins:
-
Pin Grid View: Select LED D0, D1, D2 and D3 pins as outputs (Check the schematic for your board)
-
Pin Grid View: Select RA5 and RB0 pin as switch inputs (check the schematic for your board)
-
Enable Weak Pullup if needed
-
-
Drivers>Timer:
-
Timer PLIB Selector: TMR0 & TMR1
-
Timer Enable: True
-
Interrupt Driven: True
-
Requested Period: 1 s
-
-
Drivers>Power:
-
Add power driver to project resources
-
After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:
#include "mcc_generated_files/system/system.h" #include "mcc_generated_files/power/power.h" /* * Development Board: Explorer 8 Development Board with PIC18F45K22 DIP package IC. * MCC Configuration: * System module: FOSC (1MHz_HFINTOSC/16) * TMR0, Timer Enable - True, Interrupt Driven - True, Requested Timer Period - 1 s * TMR1, Timer Enable - True, Interrupt Driven - True, Requested Timer Period - 1 s * Pins module: RD0 - GPIO Output LED for TMR0 toggle, * RD1 - GPIO Output LED for TMR1 Toggle, RD2 - GPIO Output LED not used, RD3 - GPIO Output LED for button press indication, RB0 - GPIO Input for Switch 1, RA5 - GPIO Input for Switch 2, */ void LED_PIN_ISR_RD0(void){ IO_RD0_Toggle(); //Turns the pin called 'RD0' on or off for 1s TMR0. } void LED_PIN_ISR_RD1(void){ IO_RD1_Toggle(); //Turns the pin called 'RD1' on or off for 1s TMR1. } int main(void) { SYSTEM_Initialize(); bool error_lp,error_en,error_dis; TMR0_OverflowCallbackRegister(LED_PIN_ISR_RD0); TMR1_OverflowCallbackRegister(LED_PIN_ISR_RD1); // If using interrupts in PIC18 High/Low Priority Mode you need to enable the Global High and Low Interrupts // If using interrupts in PIC Mid-Range Compatibility Mode you need to enable the Global Interrupts // Use the following macros to: // Enable the Global Interrupts INTERRUPT_GlobalInterruptEnable(); // Disable the Global Interrupts //INTERRUPT_GlobalInterruptDisable(); // Enable the Peripheral Interrupts INTERRUPT_PeripheralInterruptEnable(); // Disable the Peripheral Interrupts //INTERRUPT_PeripheralInterruptDisable(); while(1) { if(IO_RB0_PORT == 0) //Press Switch 1 { error_dis = POWER_PeripheralDisable(POWER_TMR1); if (!error_dis) { IO_RD3_SetHigh(); //SET LED D3 if peripheral is disabled and switch 1 is pressed IO_RD1_SetLow(); //CLEAR LED D1 if peripheral is disabled } error_lp = POWER_LowPowerModeEnter(POWER_IDLE_MODE); // Enter low power mode POWER_IDLE_MODE if (error_lp) { IO_RD0_SetHigh(); // Handle error if necessary if sleep mode is invalid. } } if(IO_RA5_PORT == 0) //Press Switch 2 { error_en = POWER_PeripheralEnable(POWER_TMR1); if (!error_en) { IO_RD3_SetLow(); //CLEAR LED D3 if peripheral is re-enabled and switch 2 is pressed TMR1_Initialize(); //re-initialize sequence for TMR1 TMR1_OverflowCallbackRegister(LED_PIN_ISR_RD1); } } } }
2.6.7 File Documentation
2.6.7.1 source/power.c File Reference
This is the generated driver implementation file for the POWER driver.
#include <xc.h> #include "../power.h"
2.6.7.1.1 Functions
bool POWER_LowPowerModeEnter (power_mode_t powerMode)
Enters and sets the mode in the Power module and puts the device to sleep, depending on the enum entered.
void POWER_SetDozeRatio (power_doze_t ratio)
Sets the doze ratio in the Power module depending on the enum entered.
void POWER_DozeOnExit (bool enable)
Gets true or false boolean data in Power module.
void POWER_RecoverOnInterrupt (bool enable)
Expects true or false boolean data in Power module.
bool POWER_PeripheralEnable (power_peripheral_t peripheral)
This routine enables the Peripheral depending on the enum entered.
bool POWER_PeripheralDisable (power_peripheral_t peripheral)
This routine disables the Peripheral depending on the enum entered.
void POWER_PeripheralDisableAll (void)
Disables all the Peripherals to save power.
2.6.7.1.2 Macros
#define SETTINGDATA_MASK (uint8_t)0xFF
2.6.7.1.3 Detailed Description
This is the generated driver implementation file for the POWER driver.
POWER Generated Driver File
2.6.7.1.4 Macro Definition Documentation
SETTINGDATA_MASK
#define SETTINGDATA_MASK (uint8_t)0xFF
Section: Included Files Section: POWER Macros
2.6.7.2 source/power.h File Reference
#include <stdbool.h> #include <stdint.h>
2.6.7.2.1 Functions
bool POWER_LowPowerModeEnter (power_mode_t powerMode)
Enters and sets the mode in the Power module and puts the device to sleep, depending on the enum entered.
void POWER_SetDozeRatio (power_doze_t ratio)
Sets the doze ratio in the Power module depending on the enum entered.
void POWER_DozeOnExit (bool enable)
Gets true or false boolean data in Power module.
void POWER_RecoverOnInterrupt (bool enable)
Expects true or false boolean data in Power module.
bool POWER_PeripheralEnable (power_peripheral_t peripheral)
This routine enables the Peripheral depending on the enum entered.
bool POWER_PeripheralDisable (power_peripheral_t peripheral)
This routine disables the Peripheral depending on the enum entered.
void POWER_PeripheralDisableAll (void)
Disables all the Peripherals to save power.
2.6.7.2.2 Enumerations
enum power_mode_t { POWER_NORMAL_MODE = 8, POWER_DOZE_MODE = 9, POWER_SLEEP_MODE = 10, POWER_IDLE_MODE = 11 }
Contains the available power modes.
enum power_doze_t { POWER_1_2 = 0, POWER_1_4 = 1, POWER_1_8 = 2, POWER_1_16 = 3, POWER_1_32 = 4, POWER_1_64 = 5, POWER_1_128 = 6, POWER_1_256 = 7 }
Contains the available doze ratio.
enum power_peripheral_t { POWER_IOC = 0x0001, POWER_CLKR = 0x0002, POWER_SCAN = 0x0008, POWER_CRC = 0x0010, POWER_HLVD = 0x0020, POWER_FVR = 0x0040, POWER_SYSC = 0x0080, POWER_TMR0 = 0x0101, POWER_TMR1 = 0x0102, POWER_TMR2 = 0x0104, POWER_TMR3 = 0x0108, POWER_TMR4 = 0x0110, POWER_TMR5 = 0x0120, POWER_TMR6 = 0x0140, POWER_SMT1 = 0x0180, POWER_ZCD = 0x0301, POWER_CM1 = 0x0302, POWER_CM2 = 0x0304, POWER_ACT = 0x0380, POWER_ADC = 0x0320, POWER_DAC1 = 0x0340, POWER_NCO1 = 0x0401, POWER_NCO2 = 0x0402, POWER_NCO3 = 0x0404, POWER_DSM1 = 0x0408, POWER_CWG1 = 0x0410, POWER_CWG2 = 0x0420, POWER_CWG3 = 0x0440, POWER_CCP1 = 0x0501, POWER_CCP2 = 0x0502, POWER_CCP3 = 0x0504, POWER_PWM1 = 0x0510, POWER_PWM2 = 0x0520, POWER_PWM3 = 0x0540, POWER_U1 = 0x0608, POWER_U2 = 0x0610, POWER_U3 = 0x0620, POWER_U4 = 0x0640, POWER_U5 = 0x0680, POWER_SPI1 = 0x0602, POWER_SPI2 = 0x0604, POWER_I2C1 = 0x0601, POWER_CLC1 = 0x0701, POWER_CLC2 = 0x0702, POWER_CLC3 = 0x0704, POWER_CLC4 = 0x0708, POWER_CLC5 = 0x0710, POWER_CLC6 = 0x0720, POWER_CLC7 = 0x0740, POWER_CLC8 = 0x0780, POWER_DMA1 = 0x0801, POWER_DMA2 = 0x0802, POWER_DMA6 = 0x0820, POWER_DMA3 = 0x0804, POWER_DMA4 = 0x0808, POWER_DMA5 = 0x0810 }
Contains a list of all the PLIBs available for Peripheral Module Disable (PMD).
2.6.7.2.3 Detailed Description
POWER Generated API Header File