trauSendMsg Commands

Controlling Frequency Suppression Filters

Controlling Voice Activity Detection (VAD)

Controlling Echo Cancellation

Controlling Input and Output Gain

Converting From dB to Logarithmic Units

Changing IP-Side Signal Format

Configuring Fax Relay Media Coders

Vocoder Constants

trauSendMsg Commands

trauSendMsg allows extensible commands and messages to be sent from the host to NMS board DSPs.

With vocoder DSP programs, applications can

• Enable/disable the frequency suppression filters

• Enable/disable voice activity detection (VAD)

• Control the echo canceller

• Change input and output signal level gain

• Change the IP-side signal format (G.711 only for converting mu-Law signals to A-Law signals)

With Fax Relay DSP programs, applications can

• Configure the fax relay DSP program

The following table shows trauSendMsg commands and the AG TRAU vocoder types to which they apply:

trauSendMsg Command	Description	Media Vocoders
TRAUCMD_NOTCH_CTRL	Enables and disables frequency suppression filters.	All except fax relay filters
TRAUCMD_SETVAD	Enables and disables voice activity detection (VAD).	G.723.1 and FR GSM
TRAUCMD_ECHOCNTL	Enables, disables and controls echo cancellation.	All except fax relay filters
TRAUCMD_SETGAIN	Sets vocoder input and output gain.	All except fax relay filters
TRAUCMD_CHNG_DEC	Changes the coding format in the IP packet from mu-Law to A-law.	G.711
TRAUCMD_FAXRELAY_CONFIG	Configures the Fax Relay DSP program.	Fax relay filters

Note: trauSendMsg commands can be used to dynamically configure any enabled AG TRAU channel of the specified type.

All media coders are shipped with a C language header file that defines the TRAU service trauSendMsg constants. These files are located in the nms\include directory and are named vocdef.h, where voc is the name of the media coder.

Controlling Frequency Suppression Filters

Applications can enable and disable frequency suppression for specific AG TRAU channels by invoking trauSendMsg with the msgid set to TRAUCMD_NOTCH_CTRL. This enables applications to enable and disable both DTMF and CED suppression filters with a single parameter.

Note: TRAUCMD_NOTCH_CTRL is supported by AG TRAU G.723.1 and G.729A vocoder programs.

The following parameters and values can be used with the TRAUCMD_NOTCH_CTRL command:

Parameter	Value	Description
msg_parms[0]	0	Disables DTMF suppression filter and CED tone filters (default).
msg_parms[0]	1	Enables DTMF suppression filter, and disables CED tone filters.
msg_parms[0]	2	Disables DTMF suppression filter and enables CED tone filters.
msg_parms[0]	3	Enables DTMF suppression filter and CED tone filters.

The following code sample shows enabling DTMF suppression filters and CED tone filters on an AG TRAU channel:

WORD msg_parms[16]={0};        /* Declare buffer to send down            */
msg_parms[0] = 3;        /* Enables both DTMF suppression filter and  */
                           /* CED tone filters                    */
ret= trauSendMsg( ctahd, TRAUCMD_NOTCH_CTRL, msg_parms, 1);

Note: When an application changes DTMF and/or CED suppression, the AG TRAU service returns a TRAUEVN_NOTCH_CTRL_DONE event.

Controlling Voice Activity Detection (VAD)

Applications can enable and disable voice activity detection (VAD) for specific AG TRAU channels by invoking trauSendMsg with the msgid set to TRAUCMD_SETVAD. trauSendMsg recognizes one parameter to enable VAD and one parameter to disable VAD.

The following parameters and values can be used with TRAUCMD_NOTCH_CTRL:

Parameter	Value	Description
msg_parms[0]	0	Disables VAD.
msg_parms[0]	1	Enables VAD (default).

The following code sample shows disabling VAD on an AG TRAU channel:

WORD msg_parms[16]={0};        /* Declare buffer to send down         */
msg_parms[0] = 0;        /* Disables VAD         */
ret= trauSendMsg( ctahd, TRAUCMD_SETVAD, msg_parms, 1);

Note: When an application enables voice activity detection with trauSendMsg the AG TRAU service returns an TRAUEVN_SETVAD_DONE event.

Controlling Echo Cancellation

Applications can control echo cancellation for specific AG TRAU channels by invoking trauSendMsg with the msgid set to TRAUCMD_ECHOCNTL. This command works with all AG TRAU programs.

The TRAUCMD_ECHOCNTL command gives the application the ability to:

• Inhibit or re-enable adaptation

• Enable or disable the echo suppressor

• Reset the tap coefficients of the echo model

These capabilities can be useful in diagnosing signal quality issues. In addition they provide the controls to ensure that the echo canceler meets applicable standards.

Note: In four-wire, full-duplex connections or connections that use existing network echo cancelers, vocoder echo canceler is not needed and should be disabled.

The following parameters and values are used with the TRAUCMD_NOTCH_CTRL command:

Parameter	Value	Description
msg_parms[0]	0	Freezes the echo model.
msg_parms[0]	Non-zero	Enables adaptation (default).
msg_parms[1]	0	Disables the echo suppressor.
msg_parms[1]	Non-zero	Enables the echo suppressor (default).
msg_parms[2]	0	Resets the echo canceler coefficients to allow the echo canceler to retrain. This resets the echo canceler momentarily. To reset and not retrain, send 1.
msg_parms[2]	Non-zero	Does not reset the echo model (default).

To completely disable and reset the echo canceler, set msg_parms[0], msg_parms[1], and msg_parms[2] to 0.

The following code sample shows sending an echo cancellation control message to an AG TRAU channel:

WORD msg_parms[16]={0};        /* Declare buffer to send down         */
msg_parms[0] = 0;        /* Freeze the echo model         */
msg_parms[1] = 0;        /* Disable echo suppressor         */
msg_parms[2] = 1;        /* Do not reset echo model         */
ret= trauSendMsg( ctahd, TRAUCMD_ECHOCNTL, msg_parms, 3);

Note: When an application sets echo cancellation with trauSendMsg, the AG TRAU service returns an TRAUEVN_ECHOCNTL_DONE event.

Controlling Input and Output Gain

Applications can control AG TRAU channel input and output gain by using the TRAUCMD_SETGAIN command with trauSendMsg.

A separate.h file (for example, g723def.h) defines the specific commands for each type of AG TRAU program. The following is an example:

     #define TRAUEVN_SETGAIN_DONE   0x000A210A
     #define TRAUCMD_SETGAIN        0x0A
     #define TRAU_INPUTGAIN_DEF     0x0400

The TRAUCMD_SETGAIN command enables applications to set the input or output gain (respective to the PCM side). This is set in the first two words sent down to the vocoder in the message parameters.

Parameter	Value	Description
msg_parms[0]	Gain in linear	Gain for data moving from AG TRAU program to data network side of gateway.
msg_parms[2]	Gain in linear	Gain for data moving from AG TRAU program to PSTN.

Modifications to the input gain should be set carefully. Increasing this gain by more than 6 dB can result in clipping and may adversely affect echo cancellation. The default setting is 0x0400, which corresponds to a 0 dB gain. The input and output default gains have been set to 0 dB and 0 dB, respectively.

To compute the end-to-end gain, use the following formula:

Net Gain = Input Gain + Output Gain

For example:

Net Gain = 0 dB + (-3dB) = -3 dB

Note: Plan the voice transmission level carefully to provide a balance between sufficient end-to-end voice levels and echo control. Under certain circuit conditions, (certain poor quality phones and temporary on-hook conditions) telephony circuit can oscillate or sing if the combination of the net gain and transhybrid losses exceeds 0 dB.

The following code sample shows sending a gain control message to an AG TRAU channel:

WORD msg_parms[16]={0};          /* Declare buffer to send down          */
msg_parms[0] = TRAU_INPUTGAIN_DEF;/* Gain input setting                    */
msg_parms[1] = 0x0080;          /* Output gain set to approx -18 dB          */
ret= trauSendMsg( ctahd, TRAUCMD_SETGAIN, msg_parms, 2);     

When an application alters AG TRAU channel input or output gain with trauSendMsg, the AG TRAU service returns a TRAUEVN_SETGAIN_DONE event.

Converting From dB to Logarithmic Units

To convert from dB to API logarithmic units use the following formula, where DSP 0 dB ref is equivalent to 1024 (0x0400).

(dB) = 20 log10 ( API Units ) / ( DSP 0 dB ref )

...or in terms of solving for API Units:

API Units = ( DSP 0 dB ref ) * (10^(dB/20))

The following example shows computing a 3dB gain value:

3dB API Units = 1024 * 10^(3/20)
1024 * 10^(.15)
1024 * 1.4125
1446
0x05A6

The following table shows values commonly used with the TRAUCMD_SETGAIN command:

Value	Gain	Value	Loss
0x0FED	12	0x0000	Squelch
0x0E31	11	0x0081	18
0x0CA6	10	0x0091	17
0x0B46	9	0x00A2	16
0x0A0C	8	0x00B6	15
0x08F4	7	0x00CC	14
0x07FB	6	0x00E5	13
0x071D	5	0x0101	12
0x0657	4	0x0121	11
0x05A6	3	0x0144	10
0x0509	2	0x016B	9
0x047D	1	0x0198	8
0x0400	0	0x01C9	7
		0x0201	6
		0x0240	5
		0x0286	4
		0x02D5	3
		0x032D	2
		0x0391	1

Changing IP-Side Signal Format

For the G.711 overlay only, the coding format in the IP packet can be changed between mu-Law and A-law. This facilitates trans-oceanic gateways where one gateway has E1 (with A-law G.711) PSTN interface and the other gateway is T1 (with u-law G.711) PSTN interface. The PSTN format cannot be changed for a given overlay. This would require a change to the ag.cfg file as well. The encoder and decoder format can be changed independently.

The default is no transcoding, that is, a mu-law build will set both parameters to 0 for mu-law, and an A-law build will set both parameters to 1 for A-law.

The following parameters and values can be used with the TRAUCMD_TRANSCODE command to set the encoding format of voice data sent to the data network side of the gateway:

Parameter	Value	Description
msg_parms[0]	0	Encodes data sent to data network side of gateway in mu-law format.
msg_parms[0]	1	Encodes data sent to data network side of gateway in A-law format.

The following parameters and values used with the TRAUCMD_TRANSCODE command to set the decoding format for voice data received from the data network side of the gateway:

Parameter	Value	Description
msg_parms[1]	0	Decodes data received from data network side of gateway from mu-law format.
msg_parms[1]	1	Decodes data received from data network side of gateway from A-law format.

The following code sample shows sending a format control message to a G.711 Vocoder so that the IP-side encoder format setting is mu-law, and the IP-side decoder format is A-law:

WORD msg_parms[16]={0};        /* Declare buffer to send down         */

msg_parms[0] = 0;        /* Encoder mu-law format setting         */

msg_parms[1] = 1;        /* Decoder A-law format setting         */

ret1= trauSendMsg( ctahd, TRAUCMD_TRANSCODE, msg_parms, 2);

Note: When an application sets IP-side signal format with trauSendMsg, the AG TRAU service returns an TRAUEVN_TRANSCODE_DONE event.

Configuring Fax Relay Media Coders

Applications can configure the Fax Relay media coder for specific AG TRAU channels by invoking trauSendMsg with the msgid set to TRAUCMD_FAXRELAY_CONFIG.

The following parameters and values can be used with the TRAUCMD_FAXRELAY_CONFIG command:

Parameter	Value	Description
msg_parms[0]	Valid values entries include · FAXRELAY_MODEMASK_DEFAULT · FAXRELAY_MODEMASK_DISABLE_NSF_FILTERING Does not suppress the Non-Standard-Facility messages. · FAXRELAY_MODEMASK_DISABLE_ECM Forces ECM negotiations to non-ECM mode. · FAXRELAY_MODEMASK_ENABLE_NON_STD_T38_ECM Causes ECM fax sessions to be relayed as non-ECM T.38 packets (the fax session still goes through in ECM mode) Note: Create the mode mask by using OR to concatenate these flags.	Mode mask: assigns a configuration mask.
msg_parms[1]	Valid values include · FAXRELAY_EVENTMASK_DEFAULT Reports no fax session information. · FAXRELAY_EVENTMASK_REPT_FAX_BEGIN_END Reports the beginning and ending of a fax session. · FAXRELAY_EVENTMASK_REPT_PASSED_PAGE Reports successful passing of a fax page. Note: Create the event mask by using OR to concatenate these flags.	Event mask : assigns an event mask that determines the types of unsolicited events the filter returns.
msg_parms[2]	Valid values include · FAXRELAY_MAXBITRATE_DEFAULT Attempts to connect at 14400 bits/sec · FAXRELAY_MAXBITRATE_14400 · FAXRELAY_MAXBITRATE_9600 · FAXRELAY_MAXBITRATE_4800 · FAXRELAY_MAXBITRATE_2400 · FAXRELAY_MAXBITRATE_DISABLE_FILTER Does not modify the DIS command.	Maximum bit rate: sets the maximum bit rate of the fax transmission (in bits/sec).
msg_parms[3]	Valid values for this parameter range between the values specified for FAXRELAY_TIMEOUT_MIN and FAXRELAY_TIMEOUT_MAX. The default is specified by FAXRELAY_TIMEOUT_DEFAULT. The time out parameter is specified in units of milliseconds.	Timeout: sets the session timeout value in milliseconds.

The following code sample shows the use of the TRAUCMD_FAXRELAY_CONFIG command on an AG TRAU channel:

WORD msg_parms[16]={0}; /* Declare buffer to send down */

msg_parms[0] = FAXRELAY_MODEMASK_DEFAULT; /* use default mode mask */

msg_parms[1] = FAXRELAY_EVENTMASK_REPT_FAX_BEGIN_END; /* Show fax begin and end events */

msg_parms[2] = FAXRELAY_MAXBITRATE_9600; /* Force all fax transmission to occur at 9600bps */

msg_parms[3] = 10000; /* 10 seconds timeout value */

ret= trauSendMsg( ctahd, TRAUCMD_FAXRELAY_CONFIG, msg_parms, 4);

Note: When an application sets IP-side signal format with trauSendMsg, the AG TRAU service returns an TRAUEVN_FAXRELAY_CONFIG_DONE event.

Vocoder Constants

All vocoders are shipped with a C language header file that defines the AG TRAU Service trauSendMsg constants. These files are placed in the nms\include directory and are given the name vocdef.h, where voc is the name of the vocoder.

The following table shows trauSendMsg constants for the AG TRAU service:

Constant	Value	Description
TRAUEVN_SETGAIN_DONE	0xA210A	Vocoder gain constant
TRAUCMD_SETGAIN	0xA	Vocoder gain constant
TRAU_INPUTGAIN_DEF	00400	Default input gain constant
TRAUEVN_SETVAD_DONE	0xA210C	VAD control constant
TRAUCMD_SETVAD	0xC	VAD control constant
TRAUEVN_ECHOCNTL_DONE	0xA210E	Echo Canceler control constant
TRAUCMD_ECHOCNTL	0xE	Echo Canceler control constant
TRAUEVN_CHNG_ENC_DONE	0xA210F	IP-Side formatting constant
TRAUCMD_CHNG_ENC	0xF	IP-Side formatting constant
TRAUEVN_CHNG_DEC_DONE	0xA2110	IP-Side formatting constant
TRAUCMD_CHNG_DEC	0x10	IP-Side formatting constant
TRAUCMD_FAXRELAY_CONFIG_DONE	0xA2111	Fax Relay configuration constant
TRAUCMD_FAXRELAY_CONFIG	0x11	Fax Relay configuration constant