adiCommandEchoCanceller

Sends a data array containing raw commands to an actively running echo cancellation function. Use adiCommandEchoCanceller to enable and configure echo canceller tone detection.

Supported board types

Prototype

DWORD adiCommandEchoCanceller ( CTAHD ctahd, WORD *data [], DWORD nwords)

Argument	Description
ctahd	Context handle returned by ctaCreateContext or ctaAttachContext.
data	Pointer to an array of 16-bit data containing the commands.
nwords	Number of 16-bit data words.

Return values

Return value	Description
SUCCESS
ADIERR_INVALID_CALL_STATE	Function not valid in the current call state.
CTAERR_FUNCTION_NOT_ACTIVE	Echo canceller function was not started before calling adiCommandEchoCanceller.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_SVR_COMM	Server communication error.

Events

Event	Description
ADIEVN_ECHOCANCEL_STATUS	Generated if the echo canceller enables send status mode. For information about this mode of operation, refer to echocancel.mode in ADI_START_PARMS. The echo canceller stores the status information in an event buffer. The information is arranged according to the ADI_ECHOCANCEL_STATUS_INFO structure in adidef.h.
ADIEVN_ECHOCANCEL_TONE	This event contains two words of information about the tone that was detected. See Details for information.

DSP files

The following DSP file must be loaded to the board to enable echo canceller tone detection:

For these boards...	Add this DSP file...
AG	echo_v4.m54
CG	echo_v4.f54

Refer to the board installation and developer's manual for information about MIPS usage.

Details

The echo canceller must be started before adiCommandEchoCanceller will work. For information, see Controlling echo.

This function sends three commands to the tone detector.

Command A

Use the first command to start or stop the echo canceller tone detector, configure all options, and initialize all parameters:

Word	Description	Valid range	Typical values
Word 1	Configures the echo canceller tone detector. Set bits as follows: Bit 0: 0 = stop, 1 = start Bit 1: 0 = phase reversal requested Bit 2: 0 = amplitude modulation detection requested Bit 3: 0 = send/receive switching required Bit 4: 0 = send path always if bit 3 = 1, 1 = receive path always if bit 3 = 1 Bit 5: 0 = send all events to host Bit 6: 0 = take direct control of echo canceller's NLP Bit 7: 0 = take direct control of echo canceller's bypass Bit 8: 0 = take direct control of echo canceller's reactivation after silence detection Bit 9: 0 = silence detection locks the send/receive path when silence detected	N/A	0001

Word

Description

Valid range

Typical values

Word 1

Configures the echo canceller tone detector. Set bits as follows:

Bit 0: 0 = stop, 1 = start

Bit 1: 0 = phase reversal requested
Bit 2: 0 = amplitude modulation detection requested
Bit 3: 0 = send/receive switching required
Bit 4: 0 = send path always if bit 3 = 1, 1 = receive path always if bit 3 = 1

Bit 5: 0 = send all events to host
Bit 6: 0 = take direct control of echo canceller's NLP
Bit 7: 0 = take direct control of echo canceller's bypass
Bit 8: 0 = take direct control of echo canceller's reactivation after silence detection
Bit 9: 0 = silence detection locks the send/receive path when silence detected

N/A

0001

Command B

Use the second command to specify the type of tone to be detected:

Word	Description	Valid range	Typical values
1	Tone number	0 through 3	N/A
2	Maximum frequency	[300 through 3000]	2100+15 for CED
3	Minimum frequency	[300 through 3000]	2100-15 for CED
4	Level (32). Compute the value using the following formula: 17030 x pow(10, level/10.0), where level is in dBm in the range -42 to 0.	N/A	0001
5	Qualification time (ms)	0 through 32767	500 for CED

Tone number 0 is reserved for CED detection (phase reversal and amplitude modulation detection). Templates 1 through 3 can be set to any value. The template is deactivated when maximum frequency is set to 0.

Command C

Use the third command to modify the default configuration for CED detection, including phase reversal detection and amplitude modulation:

Word	Description	Valid range	Typical values
1	Maximum periodicity (ms) (phase reversal).	0 through 32767	480
2	Minimum periodicity (ms) (phase reversal).	0 through 32767	420
3	Maximum range of amplitude (amplitude modulation detection). A tolerance is taken by the program.	0 through 32767 (0 = no detection)	6554
4	Periodicity (amplitude modulation detection). The program on periodicity requirements takes a 20 to 25 percent tolerance.	0 through 32767	67
5	Time out before path switching (send/receive path switch). The DCE detector switches back and forth from send to receive until a tone is detected. This activity provides a 50 percent MIPS load for tone detection on both send and receive paths. The function needs about 50 ms to detect a tone and lock itself.	0 through 32767	60
6	Silence threshold (echo cancellation reactivation). Use the following formula to compute the value: 17030 x pow(10, level/10.0), where level is in dBm in the range -42 to 0.	N/A	0021h
7	Silence duration. Since fax has a longer silence period, echo cancellation could be reactivated during fax protocol after the specified amount of time.	200 through 5000	NA

ADIEVN_ECHOCANCEL_TONE contains two words of information about the tone that was detected.

Word 1 indicates if the tone was a DCE tone or a single tone:

Bit number	Description
15	Type of event. If bit 15 = 0 (DCE tone detected): Bit 14 = Amplitude modulation detected Bit 13 = Phase reversals detected Bit 12 = Silence detected after DCE detection Examples: (14,13,12) = 0,0,0 (ANS) (14,13,12) = 0,1,0 (ANS) (14,13,12) = 1,0,0 (ANSam) (14,13,12) = 1,1,0 (ANSam) (14,13,12) = x,x,1 (silence after ANSxxx detection) If bit 15 = 1 (single tone detected): Bits 14,13,12 = template's number detected Examples: (14,13,12) = 0,0,1 (template 1) (14,13,12) = 0,1,0 (template 2) (14,13,12) = 0,1,1 (template 3)
11	Path number on which tone was detected. 0 = Send path or echo canceller reference path 1 = Receive path
4,3,2,1,0	Level of the tone (dB). The tone level is equal to (bits 4-0) x (-3) dBm0. Dynamic goes from 0 to -93 dBm0. Precision is ± 1.5 dB. Examples: (0,0,0,1,1) = -9 dBm0 (0,0,1,0,1) = -15 dBm0

Bit number

Description

Type of event.

If bit 15 = 0 (DCE tone detected):

Bit 14 = Amplitude modulation detected
Bit 13 = Phase reversals detected
Bit 12 = Silence detected after DCE detection

Examples:

(14,13,12) = 0,0,0 (ANS)
(14,13,12) = 0,1,0 (ANS)
(14,13,12) = 1,0,0 (ANSam)
(14,13,12) = 1,1,0 (ANSam)
(14,13,12) = x,x,1 (silence after ANSxxx detection)

If bit 15 = 1 (single tone detected):

Bits 14,13,12 = template's number detected

Examples:

(14,13,12) = 0,0,1 (template 1)
(14,13,12) = 0,1,0 (template 2)
(14,13,12) = 0,1,1 (template 3)

Path number on which tone was detected.

0 = Send path or echo canceller reference path
1 = Receive path

4,3,2,1,0

Level of the tone (dB). The tone level is equal to (bits 4-0) x (-3) dBm0. Dynamic goes from 0 to -93 dBm0. Precision is ± 1.5 dB.

Examples:

(0,0,0,1,1) = -9 dBm0
(0,0,1,0,1) = -15 dBm0

Word 2 indicates the frequency (or frequencies) detected. Because templates can be programmed for a range of tones, it is possible to detect multiple tones within the same template. The following formula is used:

2 x cos(2p x F/8000),

Examples:

(15,...,0) = 7FFFh F = 0 Hz
(15,...,0) = 3254h F = 1748 Hz
(15,...,0) = 896Ah F = 2613 Hz

When a tone is detected, the program scans all templates and locks itself on the first template that satisfies the frequency and level detected. Program templates appropriately to deal with this behavior. For example:

Template 2 = [800 - 1300] Hz, ...
Template 3 = [1000 - 1020] Hz, ...

In this example, when a 1010 Hz tone appears, the program sends back an event associated with template 2 because it is the first template that meets all criteria for the detection. Thus, DCE detection is programmed on template 0 exclusively.

Once tone is detected, no path switching is performed until the end of detection.

If bit 9 of command A is set to 1, silence duration is computed according to the time connected to the right path. For example, if silence duration is set to 400 ms, 800 ms might pass before silence is detected.

Example

// test routine that prompts for parameter values
DWORD myTestCommandEC(CTAHD ctahd)
{
    char command;
    WORD Aparms[1];
    WORD Bparms[5];
    WORD Cparms[7];

    DWORD nparms;
    WORD parms[16];
    WORD wtemp;
    DWORD dwtemp;

    promptchar ("Enter Command (A,B or C)", &command);
    switch (command)
    {
        case 'A':
            promptw ("EC Config", &Aparms[0]);
            nparms = 2;
            parms[0] = 1;    // command code "A"
            memcpy (&parms[1], Aparms, sizeof Aparms);
            break;
        case 'B':
            promptw ("Tone #",    &Bparms[0]);
            promptw ("Max Freq",  &Bparms[1]);
            promptw ("Min Freq",  Bparms[2]);
            prompt  ("Level",     &dwtemp);
            Bparms[3] = (WORD) (17030*pow(10,(dwtemp/10.0)));
            promptw ("Qual Time", &Bparms[4]);

            nparms = 6;
            parms[0] = 2;    // command code "B"
            memcpy (&parms[1], Bparms, sizeof Bparms);
            break;
        case 'C':
            promptw ("Phase rev: T_max (ms)",    &Cparms[0]);
            promptw ("Phase rev: T_min (ms)",    &Cparms[1]);
            promptw ("AM: factor (%)",                &wtemp);
            Cparms[2] = (WORD) (32767*wtemp/100);
            promptw ("AM: T (ms)",                    &Cparms[3]);
            promptw ("Tx/Rx path switching (ms)",&Cparms[4]);
            prompt ("Silence lvl (dB)",                &dwtemp);
            Cparms[5] = (WORD) (17030*pow(10,(dwtemp/10.0)));
            promptw ("Silence duration (ms)",    &Cparms[6]);

            nparms = 8;
            parms[0] = 3;    // command code "C"
            memcpy (&parms[1], Cparms, sizeof Cparms);
            break;
        default:
            printf("Invalid command\n");
            return -1;
    }
    return adiCommandEchoCanceller (ctahd, parms, nparms);
}

adiCommandEchoCanceller

Supported board types

Prototype

Return values

Events

DSP files

Details

See also

Example