icpd.h

CP detector (CPD) only reports the onset and removal of a tone. The analysis of timing (if required)

/*------------------------------------------------------------------------*
*                                                                         *
*   THIS IS AN UNPUBLISHED WORK CONTAINING CONFIDENTIAL AND PROPRIETARY   *
*   INFORMATION.  IF PUBLICATION OCCURS, THE FOLLOWING NOTICE APPLIES:    *
*      "COPYRIGHT 2001 MIKET DSP SOLUTIONS, ALL RIGHTS RESERVED"          *
*                                                                         *
*-------------------------------------------------------------------------*/ 
#ifndef ICPD_
#define ICPD_    

#include <std.h>
#include <ialg.h>

/*--------------------- public defs ---------------------------------------*/ 

#define ICPD_FR_SZ   (40)

typedef struct ICPD_Obj {
    struct ICPD_Fxns *fxns;
} ICPD_Obj;

typedef struct ICPD_Obj *ICPD_Handle;

/*
 *  ------- control interface ---------
 *
 * use it while calling algControl()
 */                          

/*  definition of Cmd param of CPD_MIKET__control(), to be or'ed 

    OFF: 
        disable detector from running.
        function CPD_process will return almost immediately.

    RESET:
        reset database variables, data saving buffers, statistics, etc.
        preserves ptr to config data. 
        
    CFG:  
    	points to config data to be used.
    
  
        */
#define ICPD_CMD_OFF      (1)
#define ICPD_CMD_RESET    (2)
#define ICPD_CMD_CFG	  (4)
#define ICPD_CMD_GET_STTS (8)


/* Configuration of CP detector */
/*  All relevant parameters are expressed in dB, scaled up with a coeff,
    so that
    
        1 dB corresponds to 512/3.0103 ~ 170.083 ~ 170 

    The scaling was chosen as a compromise:
        - to make log scale computation fast and simple;
        - to allow enough breathing space to run averaging;
        - leave some headroom for data manipulation;
        - allow non-integer values;
        - 0 corresponds to 0dBm signal (averaged over 40 samples), 
            mu-law data (8159*4 max);
        - negative values for attenuated signal;
        - min value corresponds to approx. -82.5 dBm;
        - precision is about 0.25 dB. */
#define ICPD_1DB     (170)

/*  CP detector allows user to set several thresholds
    to customize detector for particular circumstances.

    This is provided because the requirements for MF receiver
    differ from country to country, from application to
    application.

    While setting configuration is left to discretion of the
    user, it is recommended to be aware of the consequences.
    If you 'open gates' too wide, talk-off imminuty will suffer.
    If you 'close the gates' to minimal levels,
    MF detector may reject slightly noisy signals.

    The run-time configuration fields include:
    
    sNormShift: 
    	'Normalisation': number of left shifts to align data 
    	so that 0dbm0 corresponds to 2048 DC.
    	(if right shifts are required, use negative values)

    sNoiseThr: 
        Max frame energy of backgrown noise relative to signal level.
        
        Recommended range: 10...20 dB.

    sMinEnThr:
        Min frame energy to count a frame as valid.

        Recommended range -35...-20 dB.

    sStableThr:
        How current frame energy for either low freq or high freq is allowed
        to differ from it's average value.

        Recommended range 1...3 dB.

    sTwistThr:
    	either forward of inverse.
        The value has about 0.5dB headroom, 
        but allow more headroom for very noisy conditons.

    sCleanThr:
        How energy of max components shall be higher than
        any other components.

        Recommended range 20...30 dB.

    sMaxFreqDevThr
        Max allowed deviation of an 'instanteneous' frequency
        from the standartized value, calculated as:
        -10*log10(sin(2*pi*F*dlt/400)); where
        F = min of all freqs (350 Hz);
        dlt = max allowed freq offset (0.025 for 2.5%)
        pi = 3.14159265...
        
    sMinToneDuration:
        Number of good frames before START event is send 

        The mapping to tone durations (approximate):
            duration ~ sMinToneDuration*5 + 25ms.

    sMinEndDuration:
        Number of low-energy frames before END event is send 


    S16 sAbortTimeout:
        If a faulty tone happened, ignore the signal for
        for the given number of 5ms frames.

        Recommended range 3...6 (15..30ms).

    */
typedef struct ICPD_tCfg {
    Int sNormShift;
    Int sNoiseThr;
    Int sMinEnThr;
    Int sStableThr;
    Int sTwistThr;
    Int sCleanThr;
    Int sMaxFreqDevThr;
    Int sMinToneDuration;
    Int sMinEndDuration;
    Int sAbortTimeout;
} ICPD_tCfg;

typedef struct ICPD_Status {
    Int size;           /* sizeof the whole parameter struct */
    ICPD_tCfg *pCfg;   /* in: ptr to cfg to update. used if and only if CMD_CFG indicated */
    Int sLoEn;
    Int sHiEn;
    Int sLoFreqDev;
    Int sHiFreqDev;
} ICPD_Status;


/*
 *  ======== ICPD_Params ========
 *  This structure defines the parameters necessary to create an
 *  instance of a CPD object.
 *
 */                 
 

typedef struct ICPD_Params {
    Int size;           /* sizeof the whole parameter struct */
    ICPD_tCfg *pCfg;
} ICPD_Params;

/*  definitions of the report word, returned by CPD_process() */

/*  MSByte of Report */

/*  Normally, user shall get a sequence of
        EV_START,
        EV_END.
*/

/*  no changes happened this frame */
#define ICPD_EV_NONE      (0<<8)

/*  The tone was OK for prescibed MinToneDuration.
    that's a tone for sure, we can say now. */ 
#define ICPD_EV_START     (3<<8)

/*  The tone is over now. Clean and clear finish.
    The tone was followed by a relative 'silence'
    with the power level less than the threshold. */
#define ICPD_EV_END       (4<<8)

/*  something is wrong with this tone. 
    It started Ok, went on ok for several frames, 
    but something went wrong afterwards.
    As the result, it did not end properly. */
#define ICPD_EV_ABORT     (5<<8)


/*  LSByte of Report is constructed as a bit mask, where 
    bit 0 corresponds to 350 Hz 
    bit 1 corresponds to 400 Hz 
    bit 2 corresponds to 440 Hz 
    bit 3 corresponds to 480 Hz
    bit 4 corresponds to 620 Hz

    some known tones, Table 10/ EIA/TIA-464 
*/
#define ICPD_TONE_350       (0x01)
#define ICPD_TONE_400       (0x02)
#define ICPD_TONE_440       (0x04)
#define ICPD_TONE_480       (0x08)
#define ICPD_TONE_620       (0x10)

#define ICPD_TONE_DIAL      (ICPD_TONE_350|ICPD_TONE_440)
#define ICPD_TONE_RING      (ICPD_TONE_440|ICPD_TONE_480)
#define ICPD_TONE_BUSY      (ICPD_TONE_480|ICPD_TONE_620) 
#define ICPD_TONE_WAITING   (ICPD_TONE_440)  
#define ICPD_TONE_DIAL2     (ICPD_TONE_400) 

/*
 *  ======== ICPD_Fxns ========
 *  By convention the name of the variable is CPD_MIKET_ICPD, where
 *  MIKET is the vendor name.
 */
typedef struct ICPD_Fxns {
    IALG_Fxns   ialg;
    /* functions returns report word described above */
    Int         (*algProcess)(IALG_Handle handle, Int pIn[]);
} ICPD_Fxns;

/*--------------------- local defs ----------------------------------------*/ 
/*--------------------- public vars ---------------------------------------*/
/*--------------------- local vars ----------------------------------------*/
/*--------------------- local functions -----------------------------------*/
/*--------------------- public  functions ---------------------------------*/

#endif  /* ICPD_ */