emSwLib.h

Go to the documentation of this file.

/* --COPYRIGHT--,BSD
 * Copyright (c) 2020, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * --/COPYRIGHT--*/

#ifndef _EMSWLIB_H_
#define _EMSWLIB_H_

//#############################################################################
//
//
//  Group:          MSP
//  Target Device:  MSP430F677x1A, MSP430F673xA and MSP430i20xx 
//
//  (C) Copyright 2017, Texas Instruments, Inc.
//#############################################################################
// TI Release: MSP430_ENERGY_MEASUREMENT 
// Release Date: 29Jul2020
//#############################################################################


//*****************************************************************************
// includes
//*****************************************************************************
#include <msp430.h>

#include <stdint.h>
#include <stdbool.h>
#include "IQmathLib.h"
#include "QmathLib.h"

#ifdef __cplusplus

extern "C" {
#endif

//*****************************************************************************
// defines
//*****************************************************************************

 #define EM_PHASE_RESULT_CALC_VRMS                          BIT0
 #define EM_PHASE_RESULT_CALC_IRMS                          BIT1
 #define EM_PHASE_RESULT_CALC_V_PEAK                        BIT2
 #define EM_PHASE_RESULT_CALC_I_PEAK                        BIT3
 #define EM_PHASE_RESULT_CALC_POWER_FACTOR                  BIT4
 #define EM_PHASE_RESULT_CALC_FREQ                          BIT5
#define EM_PHASE_RESULT_CALC_ACTIVE_POWER                                       BIT6
#define EM_PHASE_RESULT_CALC_REACTIVE_POWER                                     BIT7
#define EM_PHASE_RESULT_CALC_APPARENT_POWER                                     BIT8
#define EM_PHASE_RESULT_CALC_ACTIVE_ENERGY                                      BIT9
#define EM_PHASE_RESULT_CALC_REACTIVE_ENERGY                            BIT10
#define EM_PHASE_RESULT_CALC_APPARENT_ENERGY                            BIT11

#define EM_PULSE_GEN_PHASE_NONE                             (0x00)
#define EM_PULSE_GEN_PHASE_A                                (0x01)
#define EM_PULSE_GEN_PHASE_B                                (0x02)
#define EM_PULSE_GEN_PHASE_C                                (0x04)
#define EM_PULSE_GEN_PHASE_D                                (0x08)
#define EM_PULSE_GEN_PHASE_E                                (0x10)
#define EM_PULSE_GEN_PHASE_F                                (0x20)
#define EM_PULSE_GEN_PHASE_NEUTRAL                          (0x40)
#define EM_PULSE_GEN_PHASE_AGGREGATE                        (0x80)

//*****************************************************************************
// typedefs
//*****************************************************************************

typedef enum _EM_message_code_
{

        EM_message_code_no_error=0,

        // 1-20 reserved for system configuration messages
    EM_message_code_pulseArray_error=1,
        EM_message_code_indPhaseMeter_error=2,
        EM_message_code_indPhasePulseDuration_error=3,
    EM_message_code_totalPhaseMeter_error=4,
    EM_message_code_totalPhasePulseDuration_error=5,

        // 21-40 reserved for algorithm configuration messages
    EM_message_code_samplingFrequency_error=21,
    EM_message_code_reactPowLength_error=22,
    EM_message_code_reactPowIIRTable_error=23,
        
        // 41-59 reserved for meter configuration messages
    EM_message_code_phaseLength_error=41,
    EM_message_code_phaseConfig_error=41,

        // 60-249 reserved for calibration messages
        EM_message_code_calibrate_invalidPhase_error=81,

        //240-255 error
        EM_message_code_error_occurred=255
} EM_message_code;

typedef enum _EM_Current_Sensor_
{
        EM_Phase_Sensor_CT=0,
        EM_Phase_Sensor_Shunt=1,
    EM_Phase_Sensor_RC=2,
} EM_Current_Sensor;

typedef int64_t EM_Power_t;

typedef uint64_t EM_Energy_t;

typedef enum _EM_Phase_
{
        EM_Phase_A=0x01,
        EM_Phase_B=0x02,
        EM_Phase_C=0x04,
        EM_Phase_D=0x08,
        EM_Phase_E=0x10,
        EM_Phase_F=0x20,
        EM_Phase_Neutral=0x40
} EM_Phase;


typedef struct _EM_Pulse_Settings_
{
        uint8_t activePulseGpioPort;
        uint8_t reactivePulseGpioPort;
        uint16_t activePulseGpioPin;
        uint16_t reactivePulseGpioPin;
    uint64_t activeEnergyCounter;
    uint16_t activeEnergyPulseRemaining;
        uint64_t reactiveEnergyCounter;
    uint16_t reactiveEnergyPulseRemaining;
} EM_Pulse_Settings;

typedef struct _EM_System_Configuration_
{
        EM_Pulse_Settings *pulseArray;
        uint8_t pulseArrayLength;
        uint64_t indPhaseMeterConstant;
        uint16_t indPhasePulseDuration;
        uint64_t totalPhaseMeterConstant;
        uint16_t totalPhasePulseDuration;
        uint8_t pulseGeneration;
} EM_System_Configuration;


typedef struct _EM_Phase_Calibration_
{
        uint32_t voltageSF;
        uint32_t currentSF;
        uint32_t activePowerSF;
        uint32_t reactivePowerSF;
        int16_t phaseCorrection;

} EM_Phase_Calibration;

typedef struct _EM_Phase_Configuration_
{
        int32_t *currentSamplePtr;
        int16_t *voltageSamplePtr;
        EM_Current_Sensor currentSensor;
        uint16_t phaseResultsSupported;
        EM_Phase_Calibration *phaseCalibPtr;
} EM_Phase_Configuration;

typedef struct _EM_Meter_Configuration_
{
        EM_Phase_Configuration *phaseConfigPtr;
        uint8_t phaseLength;
        uint8_t *meterName;
        uint8_t *libVersionNumber;
        uint8_t *meterPW;
        //~< Pointer to meter password string
} EM_Meter_Configuration;

typedef struct _EM_Algorithm_Configuration_
{
    EM_Power_t residualPowerCutoff;
    EM_Power_t totalResidualPowerCutoff;
        uint8_t mainNomFreq;
    _iq29 sqrtTwoConst;
    _iq30 energyCalcConst;
    uint16_t freqSampling;
    uint16_t reactPowIIRMinFreq;
    uint8_t reactPowIIRShift;
    uint16_t reactPowIIRLength;
    _iq30 *reactPowIIRTable;
} EM_Algorithm_Configuration;

typedef struct _EM_SW_Lib_Config_Handle_
{
        EM_System_Configuration *systemConfig;
        EM_Algorithm_Configuration *algorithmConfig;
        EM_Meter_Configuration *meterConfig;
} EM_SW_Lib_Config_Handle;

typedef struct _EM_Metrology_
{
    int16_t sampleCount;
    int64_t actPowDotProd;
    int64_t reactPowDotProd;
    int16_t vDotProd[3];
    int64_t iDotProd;
    uint16_t cycleSampleCount;
    _iq30 reactPowGConst;
    uint32_t mainPeriod;
    uint32_t prevMainPeriod;
    _iq30 oneDivSC;
    uint16_t prevSampleCount;
    uint8_t cycleCount;
} EM_Metrology;

typedef struct _EM_Phase_BG_Results_
{
    int32_t vDCEstimate;
    int16_t iDCEstimate[3];
    int16_t reactPowPrevV90;
    int16_t vPrevSample;
    int32_t rogowskiPrevI90;
    int32_t iPrevSample;
}EM_Phase_BG_Results;

typedef struct _EM_Phase_Results_
{
    uint32_t VRMS;
    uint32_t IRMS;
    uint32_t vPeak;
    uint32_t iPeak;
    int32_t powerFactor;
    uint16_t frequency;
    EM_Power_t activePower;
        EM_Power_t reactivePower;
        EM_Power_t apparentPower;
        EM_Energy_t activeEnergy;
        EM_Energy_t reactiveEnergy;
        EM_Energy_t apparentEnergy;
        EM_Phase phaseID;
} EM_Phase_Results;

typedef struct _EM_Total_Results_
{
        EM_Power_t activePower;
        EM_Power_t reactivePower;
        EM_Power_t apparentPower;
    EM_Energy_t activeEnergy;
    EM_Energy_t reactiveEnergy;
    EM_Energy_t apparentEnergy;
} EM_Total_Results;

typedef struct _EM_SW_Lib_Result_Handle_
{
        EM_Total_Results *emTotalResult;
        EM_Phase_Results *phaseResults;
        EM_Phase_BG_Results *phaseBGResults;
        EM_Metrology **phaseMetrologyPing;
    EM_Metrology **phaseMetrologyPong;
        uint8_t phaseResultsSupportedLen;
} EM_SW_Lib_Result_Handle;

//*****************************************************************************
// globals
//*****************************************************************************
extern uint16_t * EMSWLIB_EM_HAL_ADC_maxFreqCount;

extern uint16_t * EMSWLIB_EM_HAL_ADC_minFreqCount;

//*****************************************************************************
// the function prototypes
//*****************************************************************************

/*******************************************************************************
 * EM SW LIBRARY CONFIGURATION APIS
 ******************************************************************************/
//*****************************************************************************
//
//
//******************************************************************************
extern EM_message_code EM_configureEnergyMeasurement(
                EM_SW_Lib_Config_Handle *config,
                EM_SW_Lib_Result_Handle *result);

extern void EM_initDCFilters(
        EM_SW_Lib_Config_Handle *config,
        EM_SW_Lib_Result_Handle *result);

//******************************************************************************
//
// Close the Doxygen group.
//
//******************************************************************************

/*******************************************************************************
 * EM SW LIBRARY CALIBRATION APIS
 ******************************************************************************/
//*****************************************************************************
//
//
//******************************************************************************
extern void EM_initalizeCalibrationValues(
        uint8_t *pWorkingCalibration,
        uint8_t *pFlashCalibration);

extern void EM_updateFlashCalibrationValues(
        uint8_t *pWorkingCalibration,
        uint8_t *pFlashCalibration);

//******************************************************************************
//
// Close the Doxygen group.
//
//******************************************************************************

/*******************************************************************************
 * EM SW LIBRARY RESULT APIS
 ******************************************************************************/
//*****************************************************************************
//
//
//******************************************************************************
extern int16_t EM_voltageDCFilter(
        int32_t *p,
        int16_t x);

extern int32_t EM_currentDCFilter(
        int16_t p[3],
        int32_t x);

extern void EM_perSample(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_BG_Results *bgData);

extern void EM_perDataChunk(
        EM_SW_Lib_Config_Handle *config,
        EM_SW_Lib_Result_Handle *result,
        uint16_t phaseIdx);

extern void EM_delayCurrent90Degrees(EM_Metrology *metro,
                                     EM_Phase_Configuration *phase,
                                     EM_Phase_BG_Results *bgData);

extern void EM_genPulseIndPhase(
        EM_System_Configuration *config,
        EM_Pulse_Settings *pulse,
        EM_Phase_Results *result);

extern void EM_genPulseTotalPhases(
        EM_System_Configuration *config,
        EM_Pulse_Settings *pulse,
        EM_Total_Results *result);

extern void EM_updateOneDivSC(
        EM_Metrology *metro);

extern void EM_clearMetrology(
        EM_Metrology *metro);

extern void EM_updateReactPowConst(EM_Metrology *metro,
                                   EM_Phase_Results *result,
                                   EM_Algorithm_Configuration *algo);

extern EM_message_code EM_processSample(
                EM_SW_Lib_Config_Handle *config);

extern void EM_calcActivePowerMultAcc(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase);

extern void EM_calcActivePowerDiv(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_Results *result,
        EM_Algorithm_Configuration *algo);

extern void EM_calcActiveEnergy(
        EM_Metrology *metro,
        EM_Algorithm_Configuration *algo,
        EM_Phase_Results *result);

extern void EM_calcReactivePowerMultAcc(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_BG_Results *bgData);

extern void EM_calcReactivePowerDiv(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_Results *result,
        EM_Algorithm_Configuration *algo);

extern void EM_calcReactiveEnergy(
        EM_Metrology *metro,
        EM_Algorithm_Configuration *algo,
        EM_Phase_Results *result);

extern void EM_calcApparentPower(
        EM_Phase_Results *result);

extern void EM_calcApparentEnergy(
        EM_Metrology *metro,
        EM_Algorithm_Configuration *algo,
        EM_Phase_Results *result);
                
extern void EM_calcPowerFactor(
        EM_Phase_Results *result);

extern void EM_calcVRMSMultAcc(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase);

extern void EM_calcVRMSDivSqrt(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_Results *result);
                
extern void EM_calcIRMSMultAcc(EM_Metrology *metro,
                               EM_Phase_Configuration *phase);

extern void EM_calcIRMSDivSqrt(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_Results *result);
                
extern void EM_calcIPeak(
        EM_Phase_Results *result,
        EM_Algorithm_Configuration *algo);
                
extern void EM_calcVPeak(
        EM_Phase_Results *result,
        EM_Algorithm_Configuration *algo);

extern void EM_calcFreqPeriod(
        EM_Metrology *metro,
        EM_Phase_Configuration *phase,
        EM_Phase_BG_Results *bgData);

extern void EM_calcFreq(
        EM_Metrology *metro,
        EM_Phase_Results *result,
        EM_Algorithm_Configuration *algo);

extern void EM_calcTotalActivePower(
        uint8_t *phaseIdx,
        uint8_t length,
        EM_SW_Lib_Result_Handle *result);

extern void EM_calcTotalReactivePower(
        uint8_t *phaseIdx,
        uint8_t length,
        EM_SW_Lib_Result_Handle *result);

extern void EM_calcTotalApparentPower(
        uint8_t *phaseIdx,
        uint8_t length,
        EM_SW_Lib_Result_Handle *result);


extern void EM_calcTotalActiveEnergy(
        uint8_t *phaseIdx,
        uint8_t length,
        EM_SW_Lib_Result_Handle *result);

extern void EM_calcTotalReactiveEnergy(
        uint8_t *phaseIdx,
        uint8_t length,
        EM_SW_Lib_Result_Handle *result);

extern void EM_calcTotalApparentEnergy(
        uint8_t *phaseIdx,
        uint8_t length,
        EM_SW_Lib_Result_Handle *result);

//******************************************************************************
//
// Close the Doxygen group.
//
//******************************************************************************

#ifdef __cplusplus
}
#endif // extern "C"

#endif // end of  _EMSWLIB_H_ definition