# adiModifyEchoCanceller

Modifies echo cancellation parameters after echo cancellation is started.

#### Supported board types

- AG

- CG

#### Prototype

DWORD adiModifyEchoCanceller ( CTAHD ctahd, ADI_ECHOCANCEL_PARMS *parms)

Argument | Description
ctahd | Context handle returned by ctaCreateContext or ctaAttachContext.
parms | Pointer to echo cancellation parameters, as shown: typedef struct { /* parameters for echo cancellation */ WORD size; /* size of this structure */ DWORD mode; /* echo canceller mode */ DWORD filterlength; /* fiter length (msec) */ DWORD adapttime; /* filter adaptation time (msec) */ DWORD predelay; /* offset of input sample (msec) */ INT32 gain; /* receive gain (db) */ } ADI_ECHOCANCEL_PARMS ; For field descriptions and valid values, refer to ADI_START_PARMS.

#### Return values

Return values | Description
SUCCESS |
ADIERR_INVALID_CALL_STATE | Function not valid in the current call state.
CTAERR_FUNCTION_NOT_ACTIVE | Echo canceller function was not started.
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 more 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.

#### Details

The following DSP
file must be loaded to the board before running adiModifyEchoCanceller:

For these boards... | Load this DSP file...
AG | echo.m54, echo_v3.m54, or echo_v4.m54
CG | echo.f54, echo_v3.f54, or echo_v4.f54

Refer to DSP file summary for DSP file descriptions. Refer to the board installation and developer's manual for MIPS
usage.

Use this function to modify echo cancellation parameters. The echo canceller must be started for adiModifyEchoCanceller to work. For more information, see Controlling echo.

Echo canceller operation can be enabled or disabled by setting the proper bits in the mode parameter. You can also change the gain applied to the near-end input and the predelay applied to the far-end input. You cannot change the filterlength and adapttime parameters.

You must always pass a pointer to the ADI_ECHOCANCEL_PARMS structure in the call to adiModifyEchoCanceller because the parameters for this function do not have default values. The echo cancel parameters are in the NCC.X.ADI_START.echocancel structure. You must copy the individual fields to the ADI_ECHOCANCEL_PARMS structure that you pass to adiModifyEchoCanceller.

For more information about the adiModifyEchoCanceller parameter fields, refer to ADI_START_PARMS.

#### ADI_ECHOCANCEL_STATUS_INFO structure

typedef struct
{
WORD status; /* Echo canceller status flags */
WORD ERL; /* Echo Return Loss */
WORD ERLE; /* Echo Return Loss Enhancement */
WORD sndLevel; /* Level of the sent signal */
WORD rcvLevel; /* Level of the received signal */
WORD refPoint; /* Reflection point location */
} ADI_ECHOCANCEL_STATUS_INFO;

The ADI_ECHOCANCEL_STATUS_INFO structure contains the following fields:

Field | Description
status | Echo canceller status flags. See the status flag descriptions in the following table.
ERL | Echo return loss ratio. ERL is the ratio of rcvLevel to sndLevel. Compute the ERL in dBm as follows: ERLdBm = 10 x log (1/ERL)
ERLE | Echo return loss enhancement. Compute the ERLE in dBm as follows: ERLEdBm = 10 x log (rcvLevel/(rcvLevel - ERLE))
sndLevel | Power of the sent signal. Compute the sndLevel in dBm as follows: sndLeveldBm = 10 x log (sndLevel/0x3D29) where 0x3D29 is the 0 dBm reference value.
rcvLevel | Power of the received signal. Compute the rcvLevel in dBm as follows: rcvLeveldBm = 10 x log (rcvLevel/0x3D29) where 0x3D29 is the 0 dBm reference value.
refPoint | The position of the maximum value in the H register in 8 kHz sample increments. If the returned value of refPoint is 120, the reflection point is 15 ms, and a minimum tail length of 20 ms is required.

The following table describes the status flags:

Flag | Values
Status bits
0 | 0 = Normal 1 = Send status one time
1 | 0 = Normal 1 = Send status automatically
2 | 0 = Enable HPF on reference stream (not used in v3 and up) 1 = Disable HPF on reference stream
3 | 0 = Disable comfort noise generation (used in v3 and up) 1 = Enable comfort noise generation 0 = Enable HPF on echo input stream (not used in v3 and up) 1 = Disable HPF on echo input stream
Control flags
4 | 0 = Normal 1 = Reset filter taps to zero
5 | 0 = Normal 1 = Bypass echo canceler
6 | 0 = No adapt filter taps 1 = Adapt filter taps
7 | 0 = Enable NLP (echo suppressor) 1 = Disable NLP
Status flags
8 | 0 = Diverged 1 = Converged
9 | 0 = Double talk 1 = Qualifying no double talk
10 | 0 = Double talk 1 = Qualified no double talk
11 | 0 = Not suppressing output 1 = Suppressing output
12 | 0 = Normal 1 = Possible double talk, but energy still within range of estimated ERL

#### See also

adiStartProtocol

#### Example

int myDisableEchoAdapt( CTAHD ctahd )
{
ADI_ECHOCANCEL_PARMS echoParms = {0};
NCC_ADI_START_PARMS nccStartParms = {0};
/* get echo canceller parameters used by protocol for this ctahd */
ctaGetParms ( ctahd, NCC_ADI_START_PARMID, &nccStartParms,
sizeof(nccStartParms) );
echoParms.size = sizeof(ADI_ECHOCANCEL_PARMS);
echoParms.mode = nccStartParms.echocancel.mode;
echoParms.gain = nccStartParms.echocancel.gain;
echoParms.predelay = nccStartParms.echocancel.predelay;
echoParms.mode |= ADI_ECHOCANCEL_NO_ADAPT;
if( adiModifyEchoCanceller( ctahd, &echoParms ) !=SUCCESS )
{
return MYFAILURE;
}
/* update the parameters */
nccStartParms.echocancel.mode = echoParms.mode;
ctaSetParmByName( ctahd, "ncc.x.adi_start", &nccStartParms,
sizeof nccStartParms);
return MYSUCCESS;
}