5.2. Global Tone Detection (GTD)

• 5.2.1. Defining GTD Tones
• 5.2.2. Building Tone Templates
• 5.2.3. Working with Tone Templates
• 5.2.4. Tone Event Retrieval
• 5.2.5. Maximum Number of Tone Templates
• 5.2.6. Applications
• 5.2.7. PerfectCall Disconnect Tone Supervision
• Global Tone Disconnect Supervision
• Leading Edge Detection Using Debounce Time

Global Tone Detection is a feature that allows a user to define the characteristics of a tone in order to detect a tone with the same characteristics. The characteristics of a tone are defined using GTD tone templates. The tone templates contain parameters that allow the user to assign frequency bounds and cadence components. Single and dual frequency tones are detected by comparing all incoming sounds to the GTD tone templates.

GTD operates on a channel-by-channel basis and is active when the channel is off-hook, unless the system uses a DTI/xxx, in which case, GTD is always active. GTD works simultaneously with DTMF and MF tone detection.

The driver responds to a detected tone by producing either a tone event on the event queue or a digit on the digit queue. The particular response depends upon the GTD tone configuration.

Use the Global Tone Detection functions to access tone templates and enable detection of single and dual frequency tones that fall outside those automatically provided with the Voice Driver. This includes tones outside the standard DTMF set of 0-9, a-d, *, and #, and the standard MF tones 0-9, *, and a-c.

5.2.1. Defining GTD Tones

GTD tones can have an associated ASCII digit (and digit type) specified using the digit and digtype parameters in the dx_addtone( ) function. When the tone is detected, the digit is placed in the DV_DIGIT buffer and can be retrieved using the dx_getdig( ) function. When the tone is detected, either the tone event or the digit associated with the tone can be used as a termination condition to terminate I/O functions.

Termination conditions are set using the DV_TPT data structure. See the Voice Software Reference: Programmer's Guidefor information about the DV_TPT data structure.

NOTE:

If you want to terminate on multiple tones (or digits), you need to specify the terminating conditions for each tone in a separate DV_TPT data structure.

5.2.2. Building Tone Templates

When creating the tone template you can define the following:

• single or dual frequency (300-3500 Hz)
• optional ASCII digit associated with the tone template
• cadence components

Adding a tone template to a channel enables detection of a tone on that channel. Although only one tone template can be created at a time, multiple tone templates can be added to a channel. Each channel can have a different set of tone templates. Once created, tone templates can be selectively enabled or disabled.

NOTE:

A particular tone template cannot be changed or deleted. A tone template can be disabled on a channel, but to delete a tone template, all tone templates on that channel must be deleted.

The following functions are used to define tone templates:

dx_bldst( )	build a single frequency tone description
dx_blddt( )	build a dual frequency tone description
dx_bldstcad( )	build a single frequency tone cadence description
dx_blddtcad( )	build a dual frequency tone cadence description
dx_setgtdamp( )	set the GTD amplitude

NOTE:

GTD build functions define new tone templates, and dx_addtone( ) adds the tone templates to a channel.

Use dx_addtone( ) to enable detection of the tone template on a channel.

After building a tone template using a dx_bld...( ) function, dx_addtone( ) must be called to add this tone template to a channel. If the template is not added, the next call to a dx_bld...( ) function will overwrite the tone definition contained in the previous template.

dx_bldst( ) defines a simple single frequency tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels.

dx_blddt( ) defines a simple dual frequency tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels.

NOTE:

The D/41ESC, D/160SC-LS, D/240SC, D/240SC-T1, D/300SC-E1, D/320SC, DTI/240SC, DTI/241SC, DTI/300SC, DTI/301SC, LSI/81SC, and LSI/161SC boards cannot detect dual tones with frequency components closer than 65 Hz. Use a single tone description to detect dual tones that are closer together than the ranges specified above.

dx_bldstcad( ) defines a simple single frequency cadence tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels. A single frequency cadence tone has single frequency signals with specific on/off characteristics.

dx_blddtcad( ) defines a simple dual frequency cadence tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels. A dual frequency cadence tone has dual frequency signals with specific on/off characteristics.

The minimum on- and off-time for cadence detection is 40 ms on and 40 ms off.

dx_setgtdamp( ) sets the amplitudes used by GTD. The amplitudes set using dx_setgtdamp( ) will be the default amplitudes that will apply to all tones built using the dx_bld...( ) functions. The amplitudes will remain valid for all tones built until dx_setgtdamp( ) is called again and the amplitudes are changed.

The following table lists some standard Bell System Network Call Progress Tones. The frequencies are useful when creating the tone templates.

Tone	Frequency(Hz)	On Time (ms)	Off Time (ms)
Dial	350 + 440	Continuous
Busy	480 + 620	500	500
Congestion (Toll)	480 + 620	200	300
Reorder (Local)	480 + 620	300	200
Ringback	440 + 480	2000	4000

5.2.3. Working with Tone Templates

Use the following functions to add/delete tone templates or to enable/disable tone detection:

dx_addtone( )	add a tone template
dx_deltones( )	delete tone templates
dx_distone( )	disable detection of a tone
dx_enbtone( )	enable detection of a tone

dx_addtone( ) adds the tone template that was defined by the most recent GTD build-tone function call to the specified channel. Adding a tone template to a channel downloads it to the board and enables detection of tone-on and tone-off events for that tone template.

CAUTIONS

1. Each tone template must have a unique identification.

2. Errors will occur if you use dx_addtone( ) to change a tone template that has previously been added.

dx_deltones( ) removes all tone templates previously added to a channel with dx_addtone( ). If no tone templates were previously enabled for this channel, the function has no effect.

NOTE:

dx_deltones( ) does not affect tones defined by build-tone template functions and tone templates not yet defined. If you have added tones for PerfectCall Call Analysis, these tones are also deleted.

dx_distone( ) disables the detection of DX_TONEON and/or DX_TONEOFF events on a channel. Detection capability for user-defined tones is enabled on a channel by default when dx_addtone( ) is called.

dx_enbtone( ) enables the detection of DX_TONEON and/or DX_TONEOFF events on a channel. Detection capability for tones is enabled on a channel by default when dx_addtone( ) is called. The function can re-enable tones disabled by dx_distone( ).

DX_TONEON and DX_TONEOFF events are Call Status Transition (CST) events.

5.2.4. Tone Event Retrieval

To retrieve events, perform the following:

1. Call dx_addtone( ) or dx_enbtone( ) to enable tone-on/off detection.
2. Call dx_getevt( ) to wait for CST event(s). Events are returned in the DX_EBLK structure.

NOTE:

These procedures are the same as the retrieval of any other CST event, except that dx_addtone( ) or dx_enbtone( ) are used to enable event detection instead of dx_setevtmsk( ).

You can optionally specify an associated ASCII digit (and digit type) with the tone template. In this case, the tone template is treated like DTMF tones. When the digit is detected, it is placed in the digit buffer and can be used for termination. When an associated ASCII digit is specified, tone events will not be generated for that tone.

5.2.5. Maximum Number of Tone Templates

Guidelines for maximum number of tone templates are listed below and in Table 2:

• The D/21D, D/21E, D/21H and ProLine/2V boards allow a maximum of 33 tone templates each, which results in 16 tone templates per channel if apportioned evenly among the 2 channels.
• The D/4xD, D/41E, D/41ESC, D/41H and Dialog/4 boards allow a maximum of 33 tone templates each, which results in 8 tone templates per channel if apportioned evenly among the 4 channels.
• The D/81A board allows a maximum of 100 tone templates per board, which results in 12 tone templates per channel if apportioned evenly among the 8 channels.
• The D/12x board allows a maximum of 166 tone templates per board, which results in 13 tone templates per channel if apportioned evenly among the 12 channels.
• The D/160SC-LS board has a maximum of 240 tone templates per board or 15 per channel if evenly apportioned.
• The D/240SC and D/240SC-T1 boards have a maximum of 300 tone templates per board or 15 per channel if evenly apportioned.
• The D/300SC-E1 and D/320SC boards have a maximum of 450 tone templates per board or 15 per channel if evenly apportioned.
• The DTI/240SC and DTI/241SC boards have a maximum of 300 tone templates per board or 15 per channel if evenly apportioned.
• The DTI/300SC and DTI/301SC boards have a maximum of 450 tone templates per board or 15 per channel if evenly apportioned.
• The LSI/81SC and LSI/161SC boards have a maximum of 240 tone templates per board or 15 per channel if evenly apportioned.
• The maximum number of tone templates is based on tone templates that define a dual tone with a frequency detection range (bandwidth) of 62 Hz. (The detection range is the difference between the minimum and maximum defined frequencies for the tone.)
• If you use Call Analysis to identify the tri-tone Special Information Tone (SIT) sequences, Call Analysis will create tone templates internally, and this will reduce the number of tone templates that can be created by the user. Call Analysis creates one tone template for each single-frequency tone that is defined using DX_CAP. For example, if detecting the SIT tri-tone sequences per channel, the number of tone templates that can be defined by the user will be reduced by 3 per channel.
• If you create R2MF user-defined tones using r2_creatfsig( ), the voice boards will usually be able to create all 15 R2MF user-defined tones due to the overlap in frequencies for the R2MF signals. If these boards do not have sufficient memory, they may be able to support R2MF signaling through a reduced number of R2MF user-defined tones.
• If you use dx_blddt( ) (or one of the other build tone functions) or r2_creatfsig( ) to define a user-defined tone that alone or with existing user-defined tones exceeds the available memory, you will get an EDX_MAXTMPLT error.
• If you initiate Call Analysis and there is not enough memory to create the SIT tones internally, you will get a CR_MEMERR.
• The tone detection range should be limited to a maximum of 200 Hz per tone to reduce the chance of exceeding the available memory.

  NOTE:

  The dx_deltones( ) function deletes all tone templates from a specified channel and releases the memory that was used for those tone templates. When an associated ASCII digit is specified, tone events will not be generated for that tone.

Table 2. Maximum Memory and Tone Templates (for Dual Tones)

Hardware	Tone Templates Per Board	Tone Templates Per Channel
D/21D	33	16
D/4xD	33	8
D/21E	33	16
D/41E	33	8
D/41ESC	33	8
D/81A	100	12
D/121A	166	13
D/121B	166	13
D/160SC-LS	240	15
D/240SC	300	15
D/240SC-T1	300	15
D/300SC-E1	450	15
D/320SC	450	15
DTI/240SC	300	15
DTI/241SC	300	15
DTI/300SC	450	15
DTI/301SC	450	15
LSI/81SC	240	15
LSI/161SC	240	15

5.2.6. Applications

Two sample applications for Global Tone Detection are described in this section. The first application describes how to use GTD to detect a fast-busy signal to determine when a disconnect occurs. The second application describes how to use GTD for leading edge detection of a tone using debounce time.

5.2.7. PerfectCall Disconnect Tone Supervision

PerfectCall provides disconnect tone supervision, which detects a disconnect tone that occurs after a party hangs up to end a connected call. This has been implemented in such a way that it can be used easily in an application that processes loop current drop events.

The disconnect tone is a PerfectCall tone definition (TID_DISCONNECT, tone ID 257) that contains the same default values as the TID_BUSY2 tone: Frequency 1: 500 Hz (deviation 200 Hz), Frequency 2: 525 Hz (deviation 175 Hz), On-time: 550 ms (deviation 400 ms), Off-time: 550 ms (deviation 400 ms), Repetition Count: 4.

The disconnect tone definition can be customized to the needs of your application the same as any PerfectCall tone. To enable disconnect supervision and use it with PerfectCall, use the following procedure:

1. Use the TSF Configuration application to enable the disconnect tone. The tone is enabled if a check mark is shown. (The setting of this parameter is stored in the Registry, and any change to it takes effect when the application is executed rather than when the boards are started.)
   
   Optionally, you can customize the disconnect tone definition by enabling and specifying in the TSF Configuration application Advanced Options window a PBXpert Tone Set File (if one is available). Or you can customize the disconnect tone through the API functions provided for that purpose: dx_chgfreq( ), dx_chgdur( ), and dx_chgrepcnt( )
2. Use the dx_initcallp( ) function to initialize PerfectCall in your application as normal.
2. Use the dx_setevtmsk( ) function with the DM_LCOFF parameter to enable detection of loop current drop events. This step is essential to obtain disconnect supervision.
3. Use the dx_dial( ) function with Call Progress Analysis enabled to establish a connected call as normal.
   
   The TID_DISCONNECT tone is not used during Call Progress Analysis; it is automatically disabled until Call Progress Analysis ends. If a fast busy tone occurs during Call Progress Analysis, it is detected by the TID_BUSY2 tone and will terminate Call Progress Analysis.
   
   If the party hangs up and a disconnect tone is present within the parameters of the TID_DISCONNECT tone definition, PerfectCall detects the tone and generates a single loop current drop event (DX_LCOFF).

NOTE:

If you enable the disconnect tone and loop current drop events as described above and perform a dial without Call Progress Analysis, a loop current drop event occurs if a fast busy tone is encountered during the dial.

Global Tone Disconnect Supervision

Global Tone Detection can be used for disconnect supervision. When a telephone call terminates, the central office may send a momentary drop in loop current to signal the disconnect. In configurations where the voice board is connected to a Private Branch Exchange (PBX), it is likely that there will be no drop in loop current for the voice board to detect. Instead, the PBX may initiate a fast-busy signal to indicate the disconnect. Global Tone Detection can be used to detect this fast-busy signal. Perform the following to detect the signal:

1. Determine the frequencies of the signal.
2. Characterize the on/off durations and tolerances of the signal cadence.
3. Use a build-tone function to define the characteristics of a single or dual tone with cadence in a tone template.
4. Use the dx_addtone( ) function to add the GTD tone template for Global Tone Detection on each channel.

Leading Edge Detection Using Debounce Time

Rather than detecting a signal immediately, an application may want to wait for a period of time (debounce time) before the DX_TONEON event is generated indicating the detection of the signal. The dx_bldstcad( ) and dx_blddtcad( ) functions can detect leading edge debounce on-time. A tone must be present at a given frequency and for a period of time (debounce time) before a DX_TONEON event is generated. The debounce time is specified using the ontime and ondev parameters in the dx_bldstcad( ) or dx_blddtcad( ) functions.

To use this application specify the following values for the dx_bldstcad( ) or dx_blddtcad( ) function parameters listed below:

Parameter	Description
ontime	1/2 of the desired debounce time
ondev	-1/2 of the desired debounce time
offtime	0
offdev	0
repcnt	0

NOTE:

This application cannot work with the functions dx_blddt( ) and dx_bldst( ) since these functions do not have timing field parameters.

Click here to contact Dialogic Customer Engineering