idtmf.h

Express DSP compliant C55x DTMF detector software is proposed in two versions: one with a 5 ms frame

/*------------------------------------------------------------------------*
*                                                                         *
*   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"          *
*                                                                         *
*-------------------------------------------------------------------------*/ 
/* 	
        ENHANCED LOW-MIPS DTMF DETECTOR.

        This is more a technology rather than a product.
        It has its roots in sub-band echo cancellation technology and 
        a parametric version of maximum likehood spectrum estimatiom mathod.
        It is not based on Goertzel.
        It can serve as a basis to build fast voice-fax-modem discriminators,
        MF, CP detector, etc.
        The design is tailered to the newest DSPs (C55x in particulary) 
        with dual MAC and 3+ data read paths.
 
*/
#ifndef IDTMF_
#define IDTMF_    

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

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

#define IDTMF_FR_SZ   (40)

typedef struct IDTMF_Obj {
    struct IDTMF_Fxns *fxns;
} IDTMF_Obj;

typedef struct IDTMF_Obj *IDTMF_Handle;




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

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

    OFF: 
        disable detector from running.
        function DTMF_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.
    
    GETSTAT:
    	request statistics stucture to be filled.
        */
#define IDTMF_CMD_OFF      (1)
#define IDTMF_CMD_RESET    (2)
#define IDTMF_CMD_CFG	   (4)
#define IDTMF_CMD_GETSTAT  (8)


/* Configuration of DTMF 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 same definition is applied to Freq deviation, but here 

        1% of freq deviation corresponds to 170.083 (the same value).

    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 IDTMF_1DB     (170)

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

    This is provided because the requirements for DTMF receiver
    differ from country to country, from application to
    application. COs, PBXs, IVRs, Call centers, etc may have quite different
    view of what signal shall be rejected and which shall be
    accepted. 

    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,
    DTMF detector may reject slightly noisy signals, or
    signals with echoed voice (IVR w/o EC specificly).

    The run-time configuration fields include:

    sNoiseThr: 
        Max frame energy of backgrown noise relative to signal level.
        It also should cover max level of so called 'echo DTMF'.

        Recommended range: 6...15 dB.

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

        The major usage of this thr is to accomodate for input data
        which is not MSB scaled.
        If the input data is scaled down so that +3.17 dBm corresponds
        to 8159 amplitude (pure mu-law) or whatever else number, 
        change this threshold proportionally lower.

        Recommended range -35...-25 dB.

        A note of caution: 

        DTMF detector may and will detect DTMF signals
        as low as -55...65 dBm, but it is not recommended 
        to stretch acceptance range towards such low values 
        without a practical need.
        Imagine an office with 2 people in it, both using phones.
        if one person in this office dials on his/her handsfree phone 
        which echos it back as DTMF, then this echo might be picked up by 
        another person's handset and sent towards, possibly, 
        this DTMF detector, and thus reported as a normal dialed digit
        [by the second person].

    sSumEnThr:
        To set how cumulative energy in bands of 
            680...950Hz 
            1200...1650Hz
            340...450 Hz 
        is allowed to differ from 'raw' frame energy.
        If high talk-down / stutter dial tone immunity is required, 
        then allow for bigger discrepancy.

        Recommended range 1.5...5 dB.

    s2kUpThr:
        The signal above 2kHz shall be lower than the signal below 2kHz 
        by at least this threshold.

        Recommended range 10...20 dB.
    
    sVarThr:
        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.

    sFwdTwistThr:
        As per spec definiton (Fwd or Standard ...). 
        The value has about 0.5dB headroom, 
        but allow more headroom for very noisy conditons.

        Recommended value for US, CA 4dB.

    sRevTwistThr:
        As per spec definiton. 
        The value has about 0.5dB headroom, 
        but allow more headroom for very noisy conditons.

        Recommended value for US, CA 8dB.

    sPartThr:
        A low/high frequency might be lower than the respective band energy
        no more than the value.

        Recommended range 1.5...3 dB.

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

        Recommended range 6...13 dB.
            Values above 13 dB will not work at all.

    sMaxFreqDevThr:
        Max allowed deviation of an 'instanteneous' frame frequency
        from the standartized value, in percents (see IDTMF_1DB notes).
        As a guideline (in 'usual' conditions), acceptance margin will be 
            sMaxFreqDevThr - 0.35%
        rejection margin will be
            sMaxFreqDevThr + 0.15%.
        
        Range tested: 1.0...3.0%. 

        Note that the margins for sMaxFreqDevThr > 2.5%  will be 'wider'.
        Note that the amount of EV_EARLY_ON will grow if 'gates are wide open'.
        BellCore test gives the number of EV_EARLY_ONs almost doubling
        per 0.5% increase in sMaxFreqDevThr.

    sMinToneDuration:
        How long after EV_EARLY_ON was send we wait before sending
        event EV_START.

        The mapping to DTMF durations (approximate):
            Rejected if duration < sMinToneDuration*5 + 17ms.
            Accepted if duration > sMinToneDuration*5 + 22ms.

    sMinPostSilenceDuration:
        For how long relative silence (sNoiseThr) shall be present after
        the tone has ended. If so called 'echo DTMF' is present,
        adjust both sNoiseThr and sMinPostSilenceDuration to
        ignore this 'echo'.

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


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

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

    sNoiseThr, sSumEnThr, s2kUpThr, sVarThr, sPartThr, sCleanThr 
    are the major configuration component that affect 
    noise performance, dial-tone / stutter dial tone immunity,
    talk-off immunity, and talk-down performance (DTMF on the backgrownd of voice), 
    By proper configuring those thresholds, user can achieve
    desired balance. */
typedef struct IDTMF_tCfg {
    Int sNoiseThr;
    Int sMinEnThr;
    Int sSumEnThr;
    Int sVarThr;
    Int s2kUpThr;
    Int sFwdTwistThr;
    Int sRevTwistThr;
    Int sPartThr;
    Int sCleanThr;
    Int sMaxFreqDevThr;
    Int sMinToneDuration;
    Int sMinPostSilenceDuration;
    Int sAbortTimeout;
} IDTMF_tCfg;

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

typedef struct IDTMF_Params {
    Int size;           /* sizeof the whole parameter struct */
    IDTMF_tCfg *pCfg;
} IDTMF_Params;

/*  DTMF detector calculates statistics of the signal
    when it decides that it is a valid digit.

    The statistics include:

    sLoEn:
    sHiEn:
        Average energy of the max freq component in low/high band
        (on or about 697, 770, 852, 941 Hz)/
        (on or about 1209, 1336, 1477, 1633 Hz).
        The measurements are corrected to be 'precise'
        if the actual frequency differs from the nominal value
        by <= 2%.

        Average energy of the max freq component in low band

    sLoFreqDev:
    sHiFreqDev:
        Average devation of the frequency off the 'standard',
        mentioned above values.

    DTMF detector keeps this data for sMinPostSilenceDuration or
    sAbortTimeout frames after the digit ended.
    User shall retrieve this data beforehand if required.

    Data precision depends on noise and tone duration.
    If used in low-noise conditions with long digits (200ms+),
    the energies are correct with precision of about 0.6 dB,
    and offsets are correct with precision of about 0.2%. 
    For AWGN 15dB SNR, 50 ms digits, freq dev < 2%,
    freq measurement sigma ~0.5Hz for low band and ~1.5Hz for high band. */
typedef struct IDTMF_Status {
    Int size;           /* sizeof the whole parameter struct */
    IDTMF_tCfg *pCfg;   /* in: ptr to cfg to update. used if and only if CMD_CFG indicated */
    Int sLoEn;			/* out: statistics */
    Int sHiEn;
    Int sLoFreqDev;
    Int sHiFreqDev;
} IDTMF_Status;


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

/*  MSByte of Report */

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

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

/*  that's probably a tone. This event is reported after 3.7...4.6 frames,
    if the frame is 5ms. It gives 18..23 ms of accumulation time.
    given that last frame shall not be processed by a vocoder,
    and that minimal delay of 'heavy vocoders' (G.729) is 5ms,
    (7.5ms for G.723.1),
    only up to 13 ms of DTMF will 'leak' into bearer.
    this number is OK with ATM forum documents, prescribing
    that less than 20 ms of DTMF tone may be trasmitted. 
    No additional system delay to accomodate for dtmf relay required. */
#define IDTMF_EV_EARLY_ON  (1<<8)

/*  that's is not a tone.
    after EV_EARLY_ON was sent, DTMF detector may send EV_EARLY_OFF
    event to notify system that previous notification was false. */
#define IDTMF_EV_EARLY_OFF (2<<8)

/*  The tone was OK for prescibed MinToneDuration.
    that's a tone for sure, we can say now. */ 
#define IDTMF_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 IDTMF_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 IDTMF_EV_ABORT     (5<<8)


/*  LSByte of Report. */
#define IDTMF_TONE_0 (0)
#define IDTMF_TONE_1 (1)
#define IDTMF_TONE_2 (2)
#define IDTMF_TONE_3 (3)
#define IDTMF_TONE_4 (4)
#define IDTMF_TONE_5 (5)
#define IDTMF_TONE_6 (6)
#define IDTMF_TONE_7 (7)
#define IDTMF_TONE_8 (8)
#define IDTMF_TONE_9 (9)
#define IDTMF_TONE_A (10)
#define IDTMF_TONE_B (11)
#define IDTMF_TONE_C (12)
#define IDTMF_TONE_D (13)
#define IDTMF_TONE_STAR (14)
#define IDTMF_TONE_POUND (15)

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

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

#endif  /* IDTMF_ */