View source for MP114/118: Add new tones to the CPT file

{{AP}}This article describes how you can define new tones in the CPT file used by the [[Configuration guide for AudioCodes MP114/118, v5.4 and higher|MP114/118 gateway]] to disconnect calls.  
== How to terminate a call on AudioCodes MP114/118 FXO gateways ==
When the remote telephone hangs up, the PBX/CO doesn't disconnect the call, but instead signals to the gateway that the call is disconnected using one of the following methods:
* '''Detection of polarity reversal / current disconnect<br>'''
:This is the recommended method. The call is immediately disconnected after polarity reversal or current disconnect is detected on the Tel side (assuming the PBX / CO produces this signal).
:Relevant parameters: EnableReversalPolarity, EnableCurrentDisconnect, CurrentDisconnectDuration, CurrentDisconnectDefaultThreshold, and TimeToSampleAnalogLineVoltage.
* '''Detection of Reorder / Busy / Dial tones <br>'''
:The call is immediately disconnected after Reorder / Busy / Dial tone is detected on the Tel side (assuming the PBX / CO generates this tone). This method requires the correct tone frequencies and cadence to be defined in the Call Progress Tones file. If these frequencies are unknown, define them in the CPT file (the tone produced by the PBX / CO must be recorded and its frequencies analyzed). This method is slightly less reliable than the previous one. The procedure below shows how to [[#Add a tone to the Call Progress Tone file|add a tone to the Call Progress Tone file]].
:Relevant parameters: DisconnectOnBusyTone and DisconnectOnDialTone.
* '''A special DTMF code <br>'''
:A digit pattern that when received from the Tel side, indicates to the gateway to disconnect the call.
:Relevant ini file parameter: TelDisconnectCode.
* '''Detection of silence''' <br>
:The call is disconnected after silence is detected on both call directions for a specific (configurable) amount of time. The call isn’t disconnected immediately; therefore, this method should only be used as a backup mode.
:Relevant parameters: EnableSilenceDisconnect and FarEndDisconnectSilencePeriod.

== Add a tone to the Call Progress Tone file ==
To add a tone to the CPT file, take these steps: 
[[File:Audacity.JPG|thumb|right|350px|Audacity: The frequency analysis shows that the frequency is 440 Hz]]
# Make an external call (using G.711) from an AlphaCom station to an external telephone via the MP114/118 gateway.
# [[Wireshark - capture data|Capture the call using Wireshark]].
# Disconnect the call from the PBX side by hanging up the phone, and then wait approximately 30 seconds before stopping the Wireshark recording.
# In the network trace, locate the UDP stream sent from the MP114/118, and force its decoding as RTP. '''Analyze''' menu >> '''Decode As...''' >> In the Transport tab, select '''RTP'''.
# In the network trace, locate the RTP stream sent <u>from</u> the MP114/118. 
# Save the RTP payload on your PC as a *.pcm file. '''Telephony''' menu > '''RTP''' > '''Stream Analysis...''' > '''Save Payload'''. Select:
## Channels = ‘forward’ option (gives you the audio <u>from</u> the gateway)
## Format = .au
## The file name must be stored with the extension *.pcm
# Open the *.pcm file in a voice recording utility such as [http://audacity.sourceforge.net/ Audacity] or CoolEdit. 
# Locate the tone that the PBX played to indicate the disconnected call (if such a tone exists).
# Locate the attributes of the tone -- its frequency and interval (on / off time).
# Open the [[Downloads#AudioCodes_Gateway|Call Progress Tones ini file]] in a text editor (e.g. Notepad), and add the new tone at the end of the file with the attributes you found in the previous step. Ensure that you update the numbers of the successive tones and the total number of tones in the beginning of the file.
# Create a Call Progress Tones.dat file using the DConvert Utility, see procedure below.  
# Load the new file to the gateway, and then reset the gateway.
<br><br>

==Converting a CPT ini File to a Binary dat File==
The procedure below describes how to convert a Call Progress Tones (CPT) ''ini'' file to a binary *.dat file, using the TrunkPack Downloadable Conversion Utility(DConvert). The DConvert software is coming with the MP114/118, or it can be downloaded from the [[Downloads#AudioCodes_Gateway|download site]]. For detailed information on creating a CPT ''ini'' file, refer to the [[#About the Call Progress Tones File|About the Call Progress Tones File]] paragraph below.

To convert a CPT ini file to a binary dat file, take these 10 steps:
[[File:DConvert2.JPG|thumb|350px|right|The DConvert main window]]
# Start the TrunkPack Downloadable Conversion Utility (DConvert.exe); the main window opens
# Click the Process Call Progress Tones File(s) button; the 'Call Progress Tones' dialog box opens
# Under the 'Call Progress Tones File' group, click the Select File button.
# Navigate to the folder that contains the CPT ini file that you want to convert.
# Select the ini file, and then click the Open button; the name and path of both the ini file and the (output) dat file appears in the fields below the Select File button.[[File:DConvert.JPG|thumb|350px|right|Converting the .ini file to .dat file]]
# Under the 'User Data' group, enter and perform the following:
##In the 'Vendor' field, enter the vendor's name (maximum length is 256 characters).
##In the 'Version' field, enter the version number. The format is composed of two integers separated by a period '.' (e.g., 1.2, 23.4, 5.22)/
##In the 'Version Description' field, enter a brief description of this file. The maximum length is 256 characters.
# The default value of the 'CPT Version' drop-down list is Version 3. Perform one of the following:
#*If the software version you are using is prior to version 4.4, select Version 1 (to maintain backward compatibility).
#*If the software version you are using is 4.4, select Version 2.
#*Otherwise, leave the value at its default.
# Select the 'Use dBm units for Tone Levels' check box. Note that the levels of the call progress tones (in the CPT file) must be in -dBm units.
# Click the Make File button; the file is created and a message box is displayed when successfully complete.
# Close the application.
<br style="clear:both;" />

== About the Call Progress Tones File ==
The Call Progress Tones (CPT) used by the device is a binary file (with file extension dat). This file contains the definitions of the Call Progress Tones (levels and frequencies) that are detected. You can either use one of the supplied device auxiliary (dat) files or create your own file. To create your own auxiliary file, it's recommended to modify the supplied usa_tone.ini file (in any standard text editor) to suit your specific requirements, and to convert the modified ini file into binary format using the TrunkPack Downloadable Conversion Utility. The procedure on [[#Converting a CPT ini File to a Binary dat File|how to convert CPT ini file into a binary dat file]] is described above.

 Note: Only the ''dat'' file can be loaded to the device.

You can create up to 32 different Call Progress Tones, each with frequency and format attributes. The frequency attribute can be single or dual-frequency (in the range of 300 to 1980 Hz), or an Amplitude Modulated (AM). In total, up to 64 different frequencies are supported. Only eight AM tones, in the range of 1 to 128 kHz, can be configured (the detection range is limited to 1 to 50 kHz). Note that when a tone is composed of a single frequency, the second frequency field must be set to zero.

The format attribute can be one of the following:
* '''Continuous''': (e.g., dial tone) a steady non-interrupted sound. Only the 'First Signal On time' should be specified. All other on and off periods must be set to zero. In this case, the parameter specifies the detection period. For example, if it equals 300, the tone is detected after 3 seconds (300 x 10 msec). The minimum detection time is 100 msec.

* '''Cadence''': A repeating sequence of on and off sounds. Up to four different sets of on / off periods can be specified.

* '''Burst''': A single sound followed by silence. Only the 'First Signal On time' and 'First Signal Off time' should be specified. All other on and off periods must be set to zero. The burst tone is detected after the off time is completed.

You can specify several tones of the same type. These additional tones are used only for tone detection. Generation of a specific tone conforms to the first definition of the specific tone. For example, you can define an additional dial tone by appending the second dial tone's definition lines to the first tone definition in the ''ini'' file. The device reports dial tone
detection if either of the two tones is detected.

The Call Progress Tones section of the ''ini'' file comprises the following segments:
* ['''NUMBER OF CALL PROGRESS TONES''']: Contains the following key:
'Number of Call Progress Tones' defining the number of Call Progress Tones that are
defined in the file.
* ['''CALL PROGRESS TONE #X''']: containing the Xth tone definition, starting from 0 and not exceeding the number of Call Progress Tones less 1 defined in the first section (e.g., if 10 tones, then it is 0 to 9), using the following keys:
** '''Tone Type''': Call Progress Tone types:
*** '''[1]''' Dial Tone
*** '''[2]''' Ringback Tone
*** '''[3]''' Busy Tone
*** '''[7]''' Reorder Tone
*** '''[8]''' Confirmation Tone
*** '''[9]''' Call Waiting Tone - heard by the called party
*** '''[15]''' Stutter Dial Tone
*** '''[16]''' Off Hook Warning Tone
***''' [17]''' Call Waiting Ringback Tone - heard by the calling party
*** '''[23]''' Hold Tone
** '''Tone Modulation Type''': Either Amplitude Modulated (1) or regular (0).
** '''Tone Form''': The tone's format can be one of the following:
*** Continuous (1)
*** Cadence (2)
*** Burst (3)
** '''Low Freq [Hz]:''' frequency (in Hz) of the lower tone component in case of dual frequency tone, or the frequency of the tone in case of single tone. This is not relevant to Amplitude Modulated (AM) tones.
** '''High Freq [Hz]:''' frequency (in Hz) of the higher tone component in case of dual frequency tone, or zero (0) in case of single tone (not relevant to AM tones).
**''' Low Freq Level [-dBm]:''' generation level 0 dBm to -31 dBm in dBm (not relevant to AM tones).
** '''High Freq Level''': generation level. 0 to -31 dBm. The value should be set to 32 in the case of a single tone (not relevant to AM tones).
** '''First Signal On Time [10 msec]:''' 'Signal On' period (in 10 msec units) for the first cadence on-off cycle. For be continuous tones, this parameter defines the detection period. For burst tones, it defines the tone's duration.
** '''First Signal Off Time [10 msec]:''' 'Signal Off' period (in 10 msec units) for the first cadence on-off cycle (for cadence tones). For burst tones, this parameter defines the off time required after the burst tone ends and the tone detection is reported. For continuous tones, this parameter is ignored.
** '''Second Signal On Time [10 msec]:''' 'Signal On' period (in 10 msec units) for the second cadence on-off cycle. Can be omitted if there isn't a second cadence.
** '''Second Signal Off Time [10 msec]:''' 'Signal Off' period (in 10 msec units) for the second cadence on-off cycle. Can be omitted if there isn't a second cadence.
** '''Third Signal On Time [10 msec]:''' 'Signal On' period (in 10 msec units) for the third cadence ON-OFF cycle. Can be omitted if there isn't a third cadence.
** '''Third Signal Off Time [10 msec]:''' 'Signal Off' period (in 10 msec units) for the third cadence ON-OFF cycle. Can be omitted if there isn't a third cadence.
** '''Fourth Signal On Time [10 msec]:''' 'Signal On' period (in 10 msec units) for the fourth cadence ON-OFF cycle. Can be omitted if there isn't a fourth cadence.
** '''Fourth Signal Off Time [10 msec]:''' 'Signal Off' period (in 10 msec units) for the fourth cadence ON-OFF cycle. Can be omitted if there isn't a fourth cadence.
** '''Carrier Freq [Hz]:''' frequency of the carrier signal for AM tones.
** '''Modulation Freq [Hz]:''' frequency of the modulated signal for AM tones (valid range from 1 to 128 Hz).
** '''Signal Level [-dBm]:''' level of the tone for AM tones.
** '''AM Factor [steps of 0.02]:''' amplitude modulation factor (valid range from 1 to 50. Recommended values from 10 to 25).

 Notes:
 * When the same frequency is used for a continuous tone and a cadence tone, the 'Signal On Time' parameter
   of the continuous tone must have a value that is greater than the 'Signal On Time' parameter of the cadence 
   tone. Otherwise the continuous tone is detected instead of the cadence tone.
 * The tones frequency should differ by at least 40 Hz from one tone to other defined tones.

For example, to configure the dial tone to 440 Hz only, enter the following text:
 #Dial tone
 [CALL PROGRESS TONE #1]
 Tone Type=1
 Tone Form =1 (continuous)
 Low Freq [Hz]=440
 High Freq [Hz]=0
 Low Freq Level [-dBm]=10 (-10 dBm)
 High Freq Level [-dBm]=32 (use 32 only if a single tone is required)
 First Signal On Time [10msec]=300; the dial tone is detected after 3 sec
 First Signal Off Time [10msec]=0
 Second Signal On Time [10msec]=0
 Second Signal Off Time [10msec]=0


[[Category:AlphaCom - SIP Integration]]