kunlun/export/inc/bsp/iot_plc_hw_tsfm_api.h

/****************************************************************************

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_PLC_HW_TSFM_API_H
#define IOT_PLC_HW_TSFM_API_H

#include "os_types_api.h"

#ifdef __cplusplus
extern "C" {
#endif

/* define max duration time of bit data output, uint is 1us */
#define IOT_PLC_HW_TSFM_OUTPUT_MAX_TIME   500

/* define min duration time of bit data output, uint is 1us */
#define IOT_PLC_HW_TSFM_OUTPUT_MIN_TIME   100

/* define max ahead interval time of sending data relative to
 * zero-crossing point, uint is 1us
 */
#define IOT_PLC_HW_TSFM_MAX_AHEAD_TIME    1000

/* define min ahead interval time of sending data relative to
 * zero-crossing point, uint is 1us
 */
#define IOT_PLC_HW_TSFM_MIN_AHEAD_TIME    300

/* define send mode, zero-crossing perturbance method. */
#define IOT_PLC_HW_TSFM_SEND_MODE_ZC                  0
/* define send mode, pulse current injection method. */
#define IOT_PLC_HW_TSFM_SEND_MODE_LOAD                1
/* define send mode, pulse current injection method done by PA */
#define IOT_PLC_HW_TSFM_SEND_MODE_PA                  2
/* define send mode maximum */
#define IOT_PLC_HW_TSFM_SEND_MODE_MAX                 3
/* define send mode invalid */
#define IOT_PLC_HW_TSFM_SEND_MODE_INVALID IOT_PLC_HW_TSFM_SEND_MODE_MAX

/* define load decode type, not add preamble */
#define IOT_PLC_HW_TSFM_LOAD_ENCODE_RAW                 0
/* define load decode type, normal type, value is 0xAA */
#define IOT_PLC_HW_TSFM_LOAD_ENCODE_HAMMING_PREAMBLE_1  1
/* define load decode type, irregular type,
 * 1.5bit high, 1.5bit low, 1bit high, 1.5bit low, 1.5bit high.
 */
#define IOT_PLC_HW_TSFM_LOAD_ENCODE_HAMMING_PREAMBLE_2  2

/* default load parameter. 833HZ(period = 1.2ms), 33%duty, 300ms/bit */
/* default load mode modulattion signal high during time. unit: 1us */
#define IOT_PLC_HW_TSFM_LOAD_SIG_HIGH_DUR_DEF         400
/* default load mode modulattion signal low during time. unit: 1us */
#define IOT_PLC_HW_TSFM_LOAD_SIG_LOW_DUR_DEF          800
/* default load mode modulation signal period, unit: 1HZ */
#define IOT_PLC_HW_TSFM_LOAD_SIG_PERIOD_DEF           \
    (IOT_PLC_HW_TSFM_LOAD_SIG_HIGH_DUR_DEF +          \
    IOT_PLC_HW_TSFM_LOAD_SIG_LOW_DUR_DEF)

/* default load mode characters bit during time for small current . unit: 1us */
#define IOT_PLC_HW_TSFM_LOAD_CHARA_DUR_DEF            (300 * 1000)
/* default load mode characters bit during time for large current. unit: 1us */
#define IOT_PLC_HW_TSFM_LOAD_CHARA_DUR_DEF_SHORT      (150 * 1000)
/* default load mode characters bit during time for test . unit: 1us */
#define IOT_PLC_HW_TSFM_LOAD_CHARA_DUR_TEST           (80 * 1000)

/* define receive invalid energy */
#define IOT_PLC_HW_REC_INVALID_ENERGY                 0xffff
/* define receive max energy */
#define IOT_PLC_HW_REC_MAX_ENERGY                     0xfffe

/* define load capacity: */
/* constant current mode with peak value of 400mA */
#define IOT_PLC_HW_TSFM_LOAD_CAP_400MA                0
/* constant resistance mode with peak value of 2000 mA */
#define IOT_PLC_HW_TSFM_LOAD_CAP_2000MA               1

typedef struct _hw_tsfm_send_para_zc {
    /* ahead interval time of sending data relative to zero-crossing point,
     * uint is 1us. less than or equal to IOT_PLC_HW_TSFM_MAX_AHEAD_TIME,
     * greater than or equal to IOT_PLC_HW_TSFM_MIN_AHEAD_TIME.
     */
    uint32_t ahead;
    /* duration of bit data output, uint is 1us
     * less than or equal to IOT_PLC_HW_TSFM_OUTPUT_MAX_TIME,
     * greater than or equal to IOT_PLC_HW_TSFM_OUTPUT_MIN_TIME.
     */
    uint32_t dur_output;
    /* plc rising edge zc send tsfm flag, it's phase negative zc flag. */
    uint8_t is_rising;
} hw_tsfm_send_para_zc_t;

typedef struct _hw_tsfm_send_para_load {
    /* modulate pulse signal high duration time, unit: 1us */
    uint16_t pulse_high_dur;
    /* modulate pulse signal low duration time, unit: 1us */
    uint16_t pulse_low_dur;
    /* characteristics data per bit duration time, unit: 1us */
    uint32_t chara_bit_dur;
    /* load encode type, see IOT_PLC_HW_TSFM_LOAD_ENCODE_XXX */
    uint8_t  encode         :2,
    /* reserved */
             resv           :6;
} hw_tsfm_send_para_load_t;

typedef struct _hw_tsfm_send_para_pa {
    /* delay offset time, uinit: 1ms */
    uint32_t offset_time;
    /* encode frequncy tone num. each tone num is 75MHz/(1 << 14) */
    uint16_t freq_tone_num;
} hw_tsfm_send_para_pa_t;

/* send configuration structure */
typedef struct _hw_tsfm_send_cfg {
    /* specified launch phase, see IOT_PLC_PHASE_XXX */
    uint8_t  phase          :2,
    /* send mode, see IOT_PLC_HW_TSFM_SEND_MODE_XXX. */
             mod_mode       :4,
    /* no use. */
             rsvd           :2;
    /* send cnt */
    uint8_t  cnt;
    /* send mode parameters */
    union {
        /* parameters of zc mode */
        hw_tsfm_send_para_zc_t              zc;
        /* parameters of load with fixed parameter mode */
        hw_tsfm_send_para_load_t            load;
        /* parameters of pa mode */
        hw_tsfm_send_para_pa_t              pa;
    } para;
} hw_tsfm_send_cfg_t;

#pragma pack(push)      /* save the pack status */
#pragma pack(1)         /* 1 byte align */

/* send configuration structure */
typedef struct _hw_tsfm_rx_info {
    /* energy:
     *  1. for tsfm info, it's ZC average delta, unit: 1us.
     *  2. for small load branch info, it's the intensity of current change,
     *     unit is 0.1mA.
     *  3. for PA branch info, it's the energy that's quantified
     */
    uint16_t energy;
    /* noise:
     *  1. for tsfm info, it's is invalid
     *  2. for small load branch info, it's the intensity of current change,
     *      unit is 0.1mA.
     *  3. for PA branch info, it's the energy that's quantified
     */
    uint16_t noise;
    /* the phase line where the info is received, see IOT_PLC_PHASE_XXX */
    uint8_t  phase          :2,
    /* flag to mark if it is reverse zero crossing reception, only for
     * tsfm info.
     */
             is_reverse_zc  :1,
    /* flag to mark if the received tsfm info is valid, only for
     * tsfm info.
     */
             is_valid       :1,
    /* sub signal count
     * For small load topo signal, it belongs to AM signal.
     * it has two frequency points, (fc + 50)Hz and (fc- 50)Hz, which are
     * two sub signals.
     * for other ways, there is no sub signal
     */
             sub_sig_cnt    :2,
    /* reserved for further use */
             rsvd           :2;
    /* sub signal info, only valid for small load branch signal */
    struct {
        /* sub signals energy, uint is 0.1mA */
        uint16_t    energy;
        /* sub signals noise, uint is 0.1mA */
        uint16_t    noise;
    } sub_sig_info[3];
} hw_tsfm_rx_info_t;

#pragma pack(pop)   /* restore the pack status */

/**
 * @brief the hardware transformer detection listener callback function format
 * @param data_type:  type of data, see PROTO_HW_TSFM_ID_XXX.
 * @param data:  hardware receive data.
 * @param len:  length of data.
 * @param phase: physical phase, see IOT_PLC_PHASE_XXX.
 * @param energy: energy, evergy of receive data.
 */
typedef void (*iot_plc_hw_tsfm_listener_func_t)(uint8_t data_type,
    uint8_t *data, uint8_t len, hw_tsfm_rx_info_t *rx_info);

/**
 * @brief iot_plc_hw_tsfm_register_listener() - register hardware transformer
 *      detection listener callback function
 * @param exe_func:   the callback function for hardware transformer detection
 *      message listening
 * @return  ERR_FAIL  - operation failed.
 *          ERR_INVAL - operation invalid.
 *          ERR_OK    - operation successful.
 */
uint32_t iot_plc_hw_tsfm_register_listener(
    iot_plc_hw_tsfm_listener_func_t exe_func);

/**
 * @brief iot_plc_hw_tsfm_send() - hardware transformer send data
 * @param data: pointer to hardware transformer send data.
 * @param len: length of data.
 * @param cfg: send configuration.
 *      see IOT_PLC_HW_TSFM_SEND_MOD_XXX
 * @return ERR_OK    - operation successful.
 * @return otherwise - operation failed, see ERR_XXX.
 */
uint32_t iot_plc_hw_tsfm_send(uint8_t *data, uint8_t len,
    hw_tsfm_send_cfg_t *cfg);

/**
 * @brief iot_plc_hw_tsfm_get_transmitter_state() - get hardware transformer
 *            transmitter state
 * @return ERR_OK    - transformer is idle.
 * @return ERR_NOSUPP - transformer no support send.
 * @return ERR_BUSY - transformer is busy.
 */
uint32_t iot_plc_hw_tsfm_get_transmitter_state(void);

/**
 * @brief iot_plc_hw_tsfm_is_3p() - check whether 3-phase tsfm signal
 *        transmission is supported
 * @return 1 - supported, 0 - not.
 */
uint8_t iot_plc_hw_tsfm_is_3p();

/**
 * @brief iot_plc_hw_tsfm_rising_is_enable() - plc rising edge zc send tsfm is
 *        supported
 * @return 1 - supported, 0 - not.
 */
uint8_t iot_plc_hw_tsfm_rising_is_enable();

/**
 * @brief iot_plc_hw_tsfm_get_supp_mode() - get support send mode
 * @return support send mode
 */
uint8_t iot_plc_hw_tsfm_get_supp_mode(void);

/**
 * @brief   iot_plc_hw_tsfm_get_load_capacity() - get support load capacity
 * @return  load capacity, see IOT_PLC_HW_TSFM_LOAD_CAP_XXX
 */
uint8_t iot_plc_hw_tsfm_get_load_capacity(void);

#ifdef __cplusplus
}
#endif

#endif /* IOT_PLC_HW_TSFM_API_H */