afe_calibration.h

Go to the documentation of this file.

/*******************************************************************************
 *   @file   afe_calibration.h
 *   @brief  ADE9430 calibration header file
 *   @author Radu Etz (radu.etz@analog.com)
 ********************************************************************************
 * Copyright (c) 2026 Analog Devices, Inc.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. 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.
 *
 * 3. Neither the name of Analog Devices, Inc. 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 ANALOG DEVICES, INC. "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 ANALOG DEVICES, INC. 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.
 *******************************************************************************/
 
#ifndef __AFE_CALIBRATION_H__
#define __AFE_CALIBRATION_H__
 
#include <stdint.h>
#include <stdbool.h>
 
/* Calibration constants */
#define ADI_PQLIB_MAX_RMS_VALUE_CAL     52702092
#define CALIBRATION_CYCLES_50HZ         150
#define CALIBRATION_CYCLES_60HZ         180
#define SQRT_2                          1.41421356f
#define GAIN_SCALE_FACTOR               (1LL << 27)  /* 2^27 */
#define OFFSET_SCALE_FACTOR             (1LL << 15)  /* 2^15 */
 
/* 24-bit signed register limits for offset registers */
#define OFFSET_REG_MAX                  ((1L << 23) - 1)   /* +8388607 */
#define OFFSET_REG_MIN                  (-(1L << 23))      /* -8388608 */

typedef enum {
    CALIBRATION_STATE_IDLE,
    CALIBRATION_STATE_INIT,
    CALIBRATION_STATE_COLLECTING,
    CALIBRATION_STATE_CALCULATING,
    CALIBRATION_STATE_CALCULATE_ERROR_BEFORE,
    CALIBRATION_STATE_WRITING,
    CALIBRATION_STATE_VERIFY_COLLECTING,
    CALIBRATION_STATE_VERIFY_CALCULATING,
    CALIBRATION_STATE_DONE,
    CALIBRATION_STATE_ERROR
} CALIBRATION_STATE;

typedef enum {
    CALIBRATION_TYPE_GAIN,
    CALIBRATION_TYPE_OFFSET
} CALIBRATION_TYPE;

typedef enum {
    CALIBRATION_PHASE_A = 0,
    CALIBRATION_PHASE_B = 1,
    CALIBRATION_PHASE_C = 2
} CALIBRATION_PHASE;

typedef struct {
    float nominal_current;      /* Arms - for gain calibration */
    float nominal_voltage;      /* Vrms - for gain calibration */
    float offset_current;       /* Arms - for offset calibration */
    float offset_voltage;       /* Vrms - for offset calibration */
    float current_pga_gain;     /* PGA gain for current (default 1) */
    float voltage_pga_gain;     /* PGA gain for voltage (default 1) */
    float current_scale;        /* Current scale factor */
    float voltage_scale;        /* Voltage scale factor */
    int32_t i_gain_init;             /* Initial current gain coefficient */
    int32_t v_gain_init;             /* Initial voltage gain coefficient */
    int32_t i_rmsos_init;            /* Initial current RMS offset */
    int32_t v_rmsos_init;            /* Initial voltage RMS offset */
    int32_t if_rmsos_init;           /* Initial current fundamental RMS offset */
    int32_t vf_rmsos_init;           /* Initial voltage fundamental RMS offset */
} CALIBRATION_INPUT;

typedef struct {
    int32_t i_gain;             /* Computed current gain coefficient */
    int32_t v_gain;             /* Computed voltage gain coefficient */
    int32_t i_rmsos;            /* Computed current RMS offset */
    int32_t v_rmsos;            /* Computed voltage RMS offset */
    int32_t if_rmsos;           /* Computed current fundamental RMS offset */
    int32_t vf_rmsos;           /* Computed voltage fundamental RMS offset */
    /* Gain calibration errors (persistent) */
    float gain_i_error_before;  /* Gain cal: current error before */
    float gain_v_error_before;  /* Gain cal: voltage error before */
    float gain_i_error_after;   /* Gain cal: current error after */
    float gain_v_error_after;   /* Gain cal: voltage error after */
    /* Offset calibration errors (persistent) */
    float offset_i_error_before; /* Offset cal: current error before */
    float offset_v_error_before; /* Offset cal: voltage error before */
    float offset_i_error_after;  /* Offset cal: current error after */
    float offset_v_error_after;  /* Offset cal: voltage error after */
    bool done;                  /* Calibration complete flag */
} CALIBRATION_RESULT;

typedef struct {
    CALIBRATION_STATE state;
    CALIBRATION_TYPE type;
    CALIBRATION_PHASE phase;
    uint16_t cycle_count;
    uint16_t target_cycles;
    int64_t irms_sum;
    int64_t irms_sum_no_gain;
    int64_t irms_sum_no_off;
    int64_t vrms_sum;
    int64_t vrms_sum_no_gain;
    int64_t vrms_sum_no_off;
    int64_t ifrms_sum;
    int64_t ifrms_sum_no_off;
    int64_t vfrms_sum;
    int64_t vfrms_sum_no_off;
    uint32_t irms_expected;
    uint32_t vrms_expected;
    uint32_t irms_measured;
    uint32_t irms_measured_no_gain;
    uint32_t irms_measured_no_off;
    uint32_t vrms_measured;
    uint32_t vrms_measured_no_gain;
    uint32_t vrms_measured_no_off;
    uint32_t ifrms_measured;
    uint32_t ifrms_measured_no_off;
    uint32_t vfrms_measured;
    uint32_t vfrms_measured_no_off;
    CALIBRATION_INPUT input;
    CALIBRATION_RESULT result;
} CALIBRATION_CONTEXT;
 
/* Global calibration context */
extern CALIBRATION_CONTEXT calibrationCtx;

void calibration_init(void);

int calibration_start(CALIBRATION_TYPE type, CALIBRATION_PHASE phase);

int calibration_process_cycle(void);

bool calibration_is_active(void);

bool calibration_is_done(void);

void calibration_clear_done(void);

const char *calibration_get_status_string(void);

uint32_t calculate_expected_irms(const CALIBRATION_INPUT *input,
                 float rms_value);

uint32_t calculate_expected_vrms(const CALIBRATION_INPUT *input,
                 float rms_value);

int32_t calculate_gain(int32_t expected, int32_t measured);

int32_t calculate_rms_without_gain(int32_t measured, int32_t gain);

int32_t calculate_rmsos(int32_t expected, int32_t measured);

int32_t calculate_rms_without_rmsos(int32_t measured, int32_t xrmsos);
 

float calculate_error(int32_t measured, int32_t expected);
 
#endif /* __AFE_CALIBRATION_H__ */