/**************************************************************************** Copyright(c) 2019 by Aerospace C.Power (Chongqing) Microelectronics. ALL RIGHTS RESERVED. This Information is proprietary to Aerospace C.Power (Chongqing) Microelectronics and MAY NOT be copied by any method or incorporated into another program without the express written consent of Aerospace C.Power. This Information or any portion thereof remains the property of Aerospace C.Power. The Information contained herein is believed to be accurate and Aerospace C.Power assumes no responsibility or liability for its use in any way and conveys no license or title under any patent or copyright and makes no representation or warranty that this Information is free from patent or copyright infringement. ****************************************************************************/ #ifndef _IOT_EM_EXT_API_H_ #define _IOT_EM_EXT_API_H_ #ifdef __cplusplus extern "C" { #endif #include "iot_pkt_api.h" #include "iot_spi_api.h" /* energy meter extern support module id */ #define IOT_EM_EXT_MODULE_INVALID 0x00 #define IOT_EM_EXT_MODULE_ATT7022 0x01 /* energy meter extern communication hw interface */ #define IOT_EM_EXT_INTERFACE_SPI 0x00 #define IOT_EM_EXT_INTERFACE_UART 0x01 #define IOT_EM_EXT_INTERFACE_I2C 0x02 /* kunlun spi port default */ #define IOT_EM_EXT_INTERFACE_SPI_PORT 0x00 /* energy meter extern general define */ /* energy meter extern connect phase id */ #define IOT_EM_EXT_PHASE_A 0 #define IOT_EM_EXT_PHASE_B 1 #define IOT_EM_EXT_PHASE_C 2 #define IOT_EM_EXT_PHASE_ALL 3 #define IOT_EM_EXT_PHASE_CNT 4 /* energy meter extern measure parameter. start */ /* power: active power */ #define IOT_EM_EXT_MTYPE_P_P 0 /* power: reactive power */ #define IOT_EM_EXT_MTYPE_P_Q 1 /* power: apparent power */ #define IOT_EM_EXT_MTYPE_P_S 2 /* power: fundamental wave active power */ #define IOT_EM_EXT_MTYPE_P_LINE_P 3 /* power: power factor */ #define IOT_EM_EXT_MTYPE_P_FACTOR 4 /* power: active power sign */ #define IOT_EM_EXT_MTYPE_POWER_SIGN 5 #define IOT_EM_EXT_MSIGN_P_A_MASK 0x01 #define IOT_EM_EXT_MSIGN_P_A_OFFSET 0 #define IOT_EM_EXT_MSIGN_P_B_MASK 0x02 #define IOT_EM_EXT_MSIGN_P_B_OFFSET 1 #define IOT_EM_EXT_MSIGN_P_C_MASK 0x04 #define IOT_EM_EXT_MSIGN_P_C_OFFSET 2 #define IOT_EM_EXT_MSIGN_P_ALL_MASK 0x08 #define IOT_EM_EXT_MSIGN_P_ALL_OFFSET 3 #define IOT_EM_EXT_MSIGN_Q_A_MASK 0x10 #define IOT_EM_EXT_MSIGN_Q_A_OFFSET 4 #define IOT_EM_EXT_MSIGN_Q_B_MASK 0x20 #define IOT_EM_EXT_MSIGN_Q_B_OFFSET 5 #define IOT_EM_EXT_MSIGN_Q_C_MASK 0x40 #define IOT_EM_EXT_MSIGN_Q_C_OFFSET 6 #define IOT_EM_EXT_MSIGN_Q_ALL_MASK 0x80 #define IOT_EM_EXT_MSIGN_Q_ALL_OFFSET 7 /* voltage: effective voltage */ #define IOT_EM_EXT_MTYPE_U_RMS 6 /* voltage: fundamental wave effective voltage */ #define IOT_EM_EXT_MTYPE_U_LINE_RMS 7 /* current: effective electric current */ #define IOT_EM_EXT_MTYPE_I_RMS 8 /* current: fundamental wave effective current */ #define IOT_EM_EXT_MTYPE_I_LINE_RMS 9 /* energy: active energy */ #define IOT_EM_EXT_MTYPE_E_P 10 /* energy: reactive energy */ #define IOT_EM_EXT_MTYPE_E_Q 11 /* energy: apparent energy */ #define IOT_EM_EXT_MTYPE_E_S 12 /* energy: fundamental wave effective active energy */ #define IOT_EM_EXT_MTYPE_E_LINE_P 13 /* angle: voltage and current angle */ #define IOT_EM_EXT_MTYPE_ANGLE_U_I 14 /* angle: voltage angle */ #define IOT_EM_EXT_MTYPE_ANGLE_UA_UB 15 #define IOT_EM_EXT_MTYPE_ANGLE_UA_UC 16 #define IOT_EM_EXT_MTYPE_ANGLE_UB_UC 17 /* frequency */ #define IOT_EM_EXT_MTYPE_FREQ 18 /* temperature */ #define IOT_EM_EXT_MTYPE_TPSD 19 /* ec constant */ #define IOT_EM_EXT_MTYPE_EC 20 /* current: read current rms offset */ #define IOT_EM_EXT_MTYPE_I_RMS_OFFSET 21 /* voltage: read voltage rms offset */ #define IOT_EM_EXT_MTYPE_U_RMS_OFFSET 22 /* current: effective electric curren for N line */ #define IOT_EM_EXT_MTYPE_I_N_RMS 23 //TODO: add code #define IOT_EM_EXT_MTYPE_MAX 24 /* energy meter extern measure parameter. end */ /* energy meter extern calibration parameter. start */ /* power: active power */ #define IOT_EM_EXT_CTYPE_P_P_GAIN 0 #define IOT_EM_EXT_CTYPE_P_P_OFFSET 1 /* power: reactive power */ #define IOT_EM_EXT_CTYPE_P_Q_GAIN 2 #define IOT_EM_EXT_CTYPE_P_Q_OFFSET 3 /* power: apparent power */ #define IOT_EM_EXT_CTYPE_P_S_GAIN 4 /* voltage: effective voltage */ #define IOT_EM_EXT_CTYPE_U_GAIN 5 #define IOT_EM_EXT_CTYPE_U_OFFSET 6 /* current: effective electric current */ #define IOT_EM_EXT_CTYPE_I_GAIN 7 #define IOT_EM_EXT_CTYPE_I_OFFSET 8 /* phase calibration */ #define IOT_EM_EXT_CTYPE_PHASE_CALI0 9 #define IOT_EM_EXT_CTYPE_PHASE_CALI1 10 #define IOT_EM_EXT_CTYPE_PHASE_CALI2 11 #define IOT_EM_EXT_CTYPE_PHASE_REGION01 12 #define IOT_EM_EXT_CTYPE_PHASE_REGION12 13 /* temperature calibration */ #define IOT_EM_EXT_CTYPE_TPSD_OFFSET 14 /* current start up threshold */ #define IOT_EM_EXT_CTYPE_I_START 15 /* power start up threshold */ #define IOT_EM_EXT_CTYPE_P_START 16 /* power gain calculate by oneshot method */ #define IOT_EM_EXT_CTYPE_P_P_GAIN_ONESHOT 17 /* phase angle calculate by oneshot method */ #define IOT_EM_EXT_CTYPE_PHS_CALI_ONESHOT 18 /* current: effective electric current for N line */ #define IOT_EM_EXT_CTYPE_I_N_GAIN 19 /* calibration type max id */ #define IOT_EM_EXT_CTYPE_MAX 0x7F /* energy meter extern calibration parameter. end */ /* special function id */ /* soft reset extern energy meter module */ #define IOT_EM_EXT_FUNC_SW_RST 0x00 /* hardware reset extern energy meter module */ #define IOT_EM_EXT_FUNC_HW_RST 0x01 /* clear extern energy meter(HW) calibration parameter */ #define IOT_EM_EXT_FUNC_CALI_AREA_CLR 0x02 /* set extern energy meter constant parameter */ #define IOT_EM_EXT_FUNC_CALI_CONST_SET 0x03 /* get extern energy meter(HW) calibration parameter */ #define IOT_EM_EXT_FUNC_CALI_AREA_GET 0x04 /* for compitable with extend cali area introduce cali version */ /* cali version invalid */ #define IOT_EM_EXT_CALI_VERSION_INVALID (0xff) /* cali version never write version to flash */ #define IOT_EM_EXT_CALI_VERSION_BASE (0) /* cali version support base cali area and extend erea */ #define IOT_EM_EXT_CALI_VERSION_EXT (1) /* cali version add support N current */ #define IOT_EM_EXT_CALI_VERSION_EXT_V2 (2) /* target cali version */ #define IOT_EM_EXT_CALI_TARGET_VER IOT_EM_EXT_CALI_VERSION_EXT_V2 #pragma pack(push) #pragma pack(1) /* calibration data start */ /* calibration data parameter for standard and actuual mode */ typedef struct _iot_em_ext_cali_data_std_act { int32_t std; int32_t actual; } iot_em_ext_cali_data_std_act_t; /* calibration data parameter for U/I offset calibration */ typedef struct _iot_em_ext_cali_data_raw_data { uint32_t raw; } iot_em_ext_cali_data_raw_data_t; /* calibration data parameter for I/P start rate calibration */ typedef struct _iot_em_ext_cali_data_set_rate { uint32_t rate; } iot_em_ext_cali_data_set_rate_t; /* calibration data for power gain */ typedef struct _iot_em_ext_cali_data_p_gain { /* indicate data type. 0 - std actual type, others - err type */ uint8_t is_err; union { /* standard meter output error value. * e.g. 0.74%, then set err = 74 */ int32_t err; /* standard/actual value, unit: 1mW */ iot_em_ext_cali_data_std_act_t std_act; } data; } iot_em_ext_cali_data_p_gain_t; /* calibration data for power phase */ typedef struct _iot_em_ext_cali_data_p_phase { /* indicate data type. 0 - std actual type, others - err type */ uint8_t is_err; union { /* standard meter output error value. * e.g. 0.74%, then set err = 74 */ int32_t err; /* standard/actual value, unit: 1mW */ iot_em_ext_cali_data_std_act_t std_act; } data; } iot_em_ext_cali_data_p_phase_t; /* calibration data for U gain, U unit: 1mV */ typedef iot_em_ext_cali_data_std_act_t iot_em_ext_cali_data_u_gain_t; /* calibration data for I gain, I unit: 1mA */ typedef iot_em_ext_cali_data_std_act_t iot_em_ext_cali_data_i_gain_t; /* calibration data for p_gain/phase angel, unit:1W/1Var */ typedef struct { /* calibration data of P include raw and actual value */ iot_em_ext_cali_data_std_act_t p; /* calibration data of Q include raw and actual value */ iot_em_ext_cali_data_std_act_t q; } iot_em_ext_cali_p_data_oneshot_t; /* calibration data for temperature offset , T unit: 0.1 Celsius */ typedef struct { int32_t std; int32_t actual; } iot_em_ext_cali_data_tpsd_t; /* voltage channel hw input config */ typedef struct _iot_em_ext_hw_u_cfg { /* voltage channel transfer rate */ uint32_t rate; } iot_em_ext_u_cfg_t; /* current channel hw input config */ typedef struct _iot_em_ext_hw_i_cfg { /* current channel sample resistance value. unit: ohm */ uint32_t r_sample; /* current channel transfer rate */ uint32_t rate; } iot_em_ext_i_cfg_t; /* energy meter constant config */ typedef struct _iot_em_ext_cali_const { /* EC constant */ uint32_t ec; /* low 16bit */ /* voltage channel config */ iot_em_ext_u_cfg_t u_ch; /* current channel config */ iot_em_ext_i_cfg_t i_ch; } iot_em_ext_cali_const_t; /* calibration data end */ #pragma pack(pop) /* energy measure misc data */ typedef struct _iot_em_ext_meas_misc { /* EC constant */ uint16_t ec; /* phase line frequency. unit: 0.01Hz */ uint16_t freq; /* energy chip temperature. unit: 0.1 centigrade */ int16_t temperature; /* voltage angle between phaseA and phaseB. unit: 1degrees */ int16_t angle_ua_ub; /* voltage angle between phaseA and phaseC. unit: 1degrees */ int16_t angle_ua_uc; /* voltage angle between phaseB and phaseC. unit: 1degrees */ int16_t angle_ub_uc; /* current rms for N line. unit: 0.00001A */ int32_t i_n_rms; //TODO: } iot_em_ext_meas_misc_t; /* energy measure all phase common data */ typedef struct _iot_em_ext_meas_common { /* active powoer sign. 0: positive , 1: negative */ uint16_t p_sign : 1,/* 1bit */ /* reactive powoer sign. 0: positive , 1: negative */ q_sign : 1, /* reserved for further use */ rsvd0 : 14; /* power factor. unit: 0.001 */ int16_t p_factor; /* active power. unit: 0.000001KW */ int32_t p_p; /* reactive power. unit: 0.000001Kvar */ int32_t p_q; /* apparent power. unit: 0.000001KVA */ int32_t p_s; /* voltage rms. unit: 0.1V */ uint16_t u_rms; /* power angele(only phaseA/B/C). unit: 0.1degrees */ int16_t angle_u_i; /* current rms. unit: 0.00001A */ int32_t i_rms; /* active energy. unit: 1/ec kwh */ uint32_t e_p; /* reactive energy. unit: 1/ec kvarh */ uint32_t e_q; /* apparent energy. unit: 1/ec kwh */ uint32_t e_s; } iot_em_ext_meas_common_t; /* measure value ctxt */ typedef struct _iot_em_ext_meas_data { /* measure update timestamp */ uint32_t ts; /* misc measure */ iot_em_ext_meas_misc_t misc; /* total phase(phase A/B/C/All) measure */ iot_em_ext_meas_common_t phase[IOT_EM_EXT_PHASE_CNT]; } iot_em_ext_meas_data_t; /* energy measure ctxt. end */ /* energy hw config info context */ typedef struct _iot_em_ext_hw_cfg { /* communication interface between energy meter extern module and kunlun. * see IOT_EM_EXT_INTERFACE_XXX */ uint32_t interface_proto : 2, /* em extern module reset gpio */ gpio_rst : 8, rev0 : 22; /* communication interface config */ union { /* spi config info */ iot_spi_cfg_t spi; /* TODO: reserved. */ uint32_t uart; } comm; } iot_em_ext_hw_cfg_t; /* @brief measure data callback register. * * @param entry measure data buffer entry address * @return: none. */ typedef void (*iot_em_ext_meas_std_rpt_func_t)(iot_em_ext_meas_data_t \ const *entry); /* energy config info context */ typedef struct _iot_em_ext_cfg { /* communication hw config */ iot_em_ext_hw_cfg_t hw_cfg; /* measure data report callback function */ iot_em_ext_meas_std_rpt_func_t rpt; } iot_em_ext_cfg_t; /* @breif: calibration finish callback function * @param res calibration result, eg, ERR_OK or ERR_FAIL * @param reason calibration fail reason, eg IOT_EM_EXT_ONESHOT_CALI_FAIL_XXX * @param return none */ typedef void (*iot_em_ext_rpt_cali_res_cb_t)(uint8_t res, uint32_t reason); /* standard source output parameter define */ typedef struct _iot_em_ext_cali_src_para { /* input standard source voltage, unit: 0.1V */ uint16_t u; /* input stardard source current, unit: 0.01A */ uint16_t i; /* input standard source active power, unit: 0.1W */ int32_t p; /* input standard source reactive power, unit: 0.1Var */ int32_t q; } iot_em_ext_cali_src_para_t; /* calibrate defult parameter type */ typedef struct _iot_em_ext_cali_zero_para { /* u offset cali zero enable */ uint32_t u_offset_en : 1, /* i offset cali zero enable */ i_offset_en : 1, resv : 30; /* u offset reg data */ uint16_t u_offset[IOT_EM_EXT_PHASE_ALL]; /* i offset reg data */ uint16_t i_offset[IOT_EM_EXT_PHASE_CNT]; } iot_em_ext_cali_default_para_t; /* app trigger calibration, config parameter define */ typedef struct _iot_em_ext_oneshot_cali_cfg { /* input max sample times */ uint32_t max_smpl : 8, /* is calibrate default parameter enable */ is_cali_defeault_en : 1, resv : 23; /* standard source device output parameter, eg U/I/PF */ iot_em_ext_cali_src_para_t src_phase[IOT_EM_EXT_PHASE_ALL]; /* hardware config const parameter */ iot_em_ext_cali_const_t cali_const; /* calibration finish callback function */ iot_em_ext_rpt_cali_res_cb_t func; /* default para data */ iot_em_ext_cali_default_para_t default_para; } iot_em_ext_oneshot_cali_cfg_t; /* @brief read measure data from local buffer. * * @param meas_type read data type, see IOT_EM_EXT_MTYPE_XXX * @param em_ext_phase read phase id, see IOT_EM_EXT_PLC_PHASE_XXX * @param result read result. unit see iot_em_ext_meas_data_t. * @return: error code. see see ERR_XXX */ uint32_t iot_em_ext_get_meas_local(uint8_t meas_type, uint8_t em_ext_phase, int32_t *result); /* @brief read measure data from chip. * * @param meas_type read data type, see IOT_EM_EXT_MTYPE_XXX * @param is_rawdata is get measure raw data * @param em_ext_phase read phase id, see IOT_EM_EXT_PLC_PHASE_XXX * @return: return measure data */ int32_t iot_em_ext_read_meas(uint8_t meas_type, uint8_t is_rawdata, uint8_t em_ext_phase); /* @brief open energy module * * @param em_ext_cfg hw config parameters * @return: error code, see ERR_XXX */ uint32_t iot_em_ext_module_open(iot_em_ext_cfg_t *em_ext_cfg); /* @brief close energy module * * @return: error code, see ERR_XXX */ uint32_t iot_em_ext_module_close(void); /* @brief entry energy meter calibration function. * * @param req request buffer address * @param req_len request buffer byte length * @param resp response buffer address * @param resp_len response buffer byte length * @return: return response valid data length */ uint32_t iot_em_ext_cali_func_entry(uint8_t *req, uint16_t req_len, uint8_t *resp, uint16_t resp_len); /* @brief em oneshot calibration trig start * @param cfg app config calibration parameter * @retval trig calibration ok return ERR_OK, else ERR_FAIL * note : in oneshot method calibration, after standard source device output * in rate voltage range and current range, just trigger the oneshot * method process once can finish all calibration. * eg : iot_em_ext_oneshot_cali_cfg_t test = {0}; * test.src_phase[0].i = 2000; //20.00A * test.src_phase[0].u = 2200; //220.0V * test.src_phase[0].p = 22000; //2200.0W * test.src_phase[0].q = 38104; //3810.4Var * test.max_smpl = 5; * test.cali_const.ec = 1200; * test.cali_const.i_ch.rate = 3000; * test.cali_const.i_ch.r_sample = 4; * test.cali_const.u_ch.rate = 1843; * iot_em_ext_cali_oneshot_trig(&test); */ uint32_t iot_em_ext_cali_oneshot_trig(iot_em_ext_oneshot_cali_cfg_t *app_cfg); #ifdef __cplusplus } #endif #endif //_IOT_EM_EXT_API_H_