# 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

- AG

- CG

#### 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

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

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.

#### See also

adiModifyEchoCanceller

#### 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);
}