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

Table 2-5. 
All supported 8-bit PIC DevicesAll 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.

Version: POWER Driver Version 1.0.0
Enumerations
Functions

2.6.5.1.2 Function Documentation

POWER_DozeOnExit()

void POWER_DozeOnExit (bool enable)

Gets true or false boolean data in Power module.

Parameters:
enable

Sets/Clears Doze on Exit

Returns:

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

Parameters:
powerMode

Enters different power modes, specified by an enum of the type power_mode_t.

Return values:
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.

Parameters:
peripheral

disable, specified as an enum of the type power_peripheral_t.

Return values:
True

Enum is invalid

False

Enum is valid

POWER_PeripheralDisableAll()

void POWER_PeripheralDisableAll (void )

Disables all the Peripherals to save power.

Parameters:
None.
Returns:

None.

POWER_PeripheralEnable()

bool POWER_PeripheralEnable (power_peripheral_t peripheral)

This routine enables the Peripheral depending on the enum entered.

Parameters:
peripheral

enable, specified as an enum of the type power_peripheral_t.

Return values:
True

Enum is invalid

False

Enum is valid

POWER_RecoverOnInterrupt()

void POWER_RecoverOnInterrupt (bool enable)

Expects true or false boolean data in Power module.

Parameters:
enable

Sets/Clears Recover-on-Interrupt

Returns:

None.

POWER_SetDozeRatio()

void POWER_SetDozeRatio (power_doze_t ratio)

Sets the doze ratio in the Power module depending on the enum entered.

Parameters:
ratio

enter different doze ratios, specified as an enum of the type power_doze_t.

Returns:

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 Configuration
  • 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

Timer Configuration
  • 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

2.6.7.1.3 Detailed Description

This is the generated driver implementation file for the POWER driver.

POWER Generated Driver File

Version: POWER Driver Version 1.0.0

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

2.6.7.2.2 Enumerations

2.6.7.2.3 Detailed Description

POWER Generated API Header File

2.6.7.3 source/power_example.dox File Reference