




Mercury Tone Generator

Component Interface Specification



Sign Off Authorization


Luke Kiernan_________________	__________________________________	Date:	__________
Author/Firmware Group Leader	Signature

Gerry Lachac________________	__________________________________	Date:	__________
Host Software Group Leader	Signature















	Date:	10/10/02
	Revision	Revision A0.8from Summary Info dialog box Subject  field
	Filename: 	tgendefs.doc
	Author: 	Christian J. Chubafrom Summary Info dialog box Author field
	Document #:	SWS-0225 from Summary Info dialog box Keywords field


DIALOGIC CONFIDENTIAL

TABLE OF CONTENTS
1.	Overview	3
1.1.	Revision History	3
1.2.	Purpose	3
1.3.	Scope	4
1.4.	References	5
1.5.	Definitions	5
2.	Theory of Operation	6
2.1.	Introduction	6
2.2.	Initialization and Exit	6
2.3.	Parameters	6
2.4.	Message Structure	6
3.	Environmental Requirements	7
3.1.	Hardware	7
3.2.	Dialogic Software	7
3.3.	File Names	7
4.	Communication Protocol	8
4.1.	Component Interface	8
4.2.	Error Handling	8
5.	Application Overview	9
5.1.	Defining Tone Signals	9
5.2. Playing Tones	10
5.4. Enabling Tone Sets	10
5.5.	Run Time Control Actions	11
6.	Message Set	12
6.1.	MsgCreateTone	14
6.2.	MsgCreateToneCmplt	20
6.3.	MsgDeleteTone	21
6.4.	MsgDeleteToneCmplt	22
6.5.	MsgPlayTone	23
6.6.	MsgPlayToneCmplt	24
6.7.	MsgPlaySequence	25
6.8.	MsgPlaySequenceCmplt	26
6.9.	MsgDial	27
6.10.	MsgDialCmplt	28
6.11.	MsgStop	29
6.12.  WgenInfo	30
6.13.	WgenInfoCmplt	31
6.14.	R2MFSet	32
6.15.	R2MFSetCmplt	33
6.16.	MsgDialx	34
6.17.	MsgPlayTonex	36
6.18.	MsgPlaySequencex	37
7.	Parameters	39
8.	Error Codes	40
9. Attributes	42
10.	Event Types	43
11.	RTC Actions	44
12. Miscellaneous Equates	45
1.	Overview
The Mercury Tone Generator Component is the Control Processor Firmware Component of the Mercury Signal Computing Resource - Tone Generator. It is the Primary Firmware Component  for this Resource supporting the front-end processing of all messages from the Mercury Host Tone Generator. It is also a sharable Component and may be accessed simultaneously by more than one other Component. Its main use is for generating tones related to call setup e.g. dialing, and for sending any application specific tones once a call has been setup. This Component supports messages from the Standard Mercury Kernel Message Set (see ref#3), the Standard Component Message Set (see ref#5) as well as its own Component specific message set. This document describes the Component specific message set for the Mercury Tone Generator Component. 
A list of parameters, event types and error codes supported by this Component are also provided.
In addition to the written description of each message there is a Mercury Message Definition Language (MMDL) representation of each of the messages embedded in the description. This allows a C header file of equates and definitions defining field descriptors and message types to be generated for each of the messages from this document using the MMDL Translation Utility. These values are then used as input to the appropriate Kernel messaging service routines for reading and writing messages to and from this Component.   
1.1.	Revision History

REVISION HISTORY
Rev.
Date of Change
Description of Change
Rev Originator
0.1
5/11/95
Initial Release
Chris Chuba
1.0
7/11/95
Major clean up for first Release.
Luke Kiernan
A
7/13/95
Updates based on review of 1.0:
Added inter-digit delay as field in MsgPlaySequence and MsgDial
Luke Kiernan
A0.1
7/17/95
Fixed some MMDL bugs.
Luke Kiernan
A0.2
12/6/96
Modified the dial and play sequence command, added parameter.
Message numbers start at 0x0500 for MDK.A108 release
Chris Chuba
A0.3
12/10/99
Added R2MFSet and WgenInfo commands for R2MF
Tyshaun Hawkins
A0.4
01/29/2001
Added #define Tgen_MAXNUMSEGS and
                        Tgen_MAXLABELSIZE
Amin Rhemtulla
Da-ming Chiang
A0.5
10/25/2001
Changed type of NextSeg in MsgCreateTone to int32, for supporting continuous play of multi-segment tone.
Xiao Kim Ma
A0.6
3/15/02
Added MsgDialx., MsgPlaySequencex and MsgPlayTonex. Corrected ordering errors with "mbuf" and "varstart" operators.
Arthur F. Elwell
A0.7
7/22/02
Changed structure element 'Char' to 'Character' in MsgDial and MsgDialx to avoid syntax conflicts in TSC component.
Arthur F. Elwell
A0.8
10/10/02
Removed "NotUsed" fields from MsgDial and MsgPlaySequence for backward compatibility.
Added #define for Tgen_MsgDial_String_varStart  to compensate for its loss when A0.6 ordering errors were corrected.
Arthur F. Elwell





1.2.	Purpose
This purpose of this document is to describe the message interface to the Mercury Tone Generator Component on the Mercury platform. The defined message set is the means by which all other Components, including the Host Software, communicate with the Tone Generator Component. This document will be used by developers of Host Software and Firmware for the Mercury Signal Computing Resource - Tone Generator.
1.3.	Scope
This document defines all of the component specific messages that the Mercury Tone Generator Component may send and receive.
For each message, all of the message specific data is specified. 
This document  also defines all of the parameters, event types and error codes that apply to this Component and a description of the functionality of each message.

1.4.	References

Ref. #
Description
Revision
Date
Document #

Mercury Kernel Architecture Specification
1.0
November 1994
SWS-0048

Mercury Kernel API Specification
1.01
November 1994
SWS-0049

Mercury Kernel Standard Messages Set
1.0
April 1995
SWS-0191
4.
Mercury Message Definition Language Specification
0.4
November 1994
SWS-0138
5.
Standard Interface Spec for Mercury Components
3.0
June 1995
SWS-0143
6.
Mercury Signal Computing Resource - Tone Generator SRS
A
March 1995
SYS-PR-040
7.
Mercury Signal Computing Resource - Tone Generator SAS
A
May 1995
SYS-PA-010
8.
Mercury Standard Waveform Generator Component Interface Spec
A
July 1995
SWS-0238

1.5.	Definitions

	dBm		-	An absolute measure of power in decibels relative to 1 milliwatt.
	dBm0		-	A relative measure of power. Relative to 0 TLP.
	TLP		-	Transmission Level Point. A reference point relative to which signal level 						measurements are made.
	0 TLP		-	A Transmission Level Point at which a 0 dBm signal is applied. Also, TLP0.
2.	Theory of Operation
2.1.	Introduction
The Mercury Tone Generator Resource provides a method for defining tone signals and then playing these tone signals to a predefined output stream, usually bound for a particular network interface. The Tone Generator Component provides the front-end message processing for all requests from the Host software to implement the Tone Generator features. It also provides an interface to a Telephony Service Provider Resource to create and play tone signals as part of a call setup. An Instance of the Tone Generator Component is known as a Tone Generator Instance.
The Dialogic Mercury Tone Generator Component abides by a set of  guidelines for Dialogic Mercury Messages as documented in the ref #5.
2.2.	Initialization and Exit
The Mercury Tone Generator Component must be started before it becomes active in the system. At initialization time a Std_MsgInit message is sent to the Mercury Tone Generator Component level. This is usually sent from a host configuration manager. On receiving this message the Component performs its own proprietary initialization sequence; initializes any Component  level data, creates the required number of Instances etc.
Likewise, the Mercury Tone Generator Component may be stopped or shut down. This typically happens when the module to which the Mercury Tone Generator Component belongs was about to be unloaded. The Mercury Tone Generator Component receives the Std_MsgExit message and shuts itself down in its own proprietary way; removing its instances, releasing memory etc.
2.3.	Parameters
Parameters are defined for, among other things, controlling the behavior of the Mercury Tone Generator Component or its Instances. Parameters may be defined at a Component or Instance level. The Instance level parameters will have the Component level parameter values as their default upon allocation. The Component level parameters will have the Dialogic factory settings of these parameters as their defaults when started. The Mercury Tone Generator Component uses the Std_MsgSetParm and Std_MsgGetParm messages to allow their parameters to be set and read. Parameters may be set or read while a Component or Instance is active or idle.
2.4.	Message Structure
The Mercury Kernel API Specification defines the standard Mercury Message Format and the methods for building and reading Mercury messages. 
3.	Environmental Requirements
3.1.	Hardware
The Mercury Tone Generator Component firmware resides on the Control Processor of the standard Mercury platform. 
3.2.	Dialogic Software
The Mercury Tone Generator Component firmware will be downloaded to the platform using the standard Mercury Downloader for the Operating System of choice on the host. Once downloaded it communicates with other components in the system and with the host via the Mercury Kernel. To complete the tone generation process the Mercury Tone Generator Component will interact with the Waveform Generator Component on the various Signal Processors on the platform. This Waveform Generator Component must be present along with the Tone Generator Component in order to successfully generate tones.
The Mercury Tone Generator Component may be accessed directly from host software.
3.3.	File Names
The TGENDEFS.H file will contain the definitions of all Tone Generator Component messages, parameters and equates.
4.	Communication Protocol
4.1.	Component Interface
The Mercury Tone Generator Component receives standard Mercury messages as input. The content of these messages will determine the functionality required. Messages are sent and received using the qMsgWrite and qMsgRead functions provided by the Mercury Kernel.
4.2.	Error Handling
All error conditions are returned using the standard Std_MsgError message with the message that caused the error and the reason for error identified in this message.
5.	Application Overview
This section explains how the Mercury Tone Generator Component messages are used to implement various features visible to client software.
5.1.	Defining Tone Signals
Tone Signal Definition is the ability to predefine tone signal descriptions and then reference those descriptions later to generate tones. Tone signal must be predefined before they can be played. The Tone Generator Component provides a MsgCreateTone message to allow a client to define a tone. This is a Component Level command and all tones defined in this way are available for use by any Instance of the Tone Generator Component. It is thought that most clients will predefine all of the tones that it intends to use at initialization time, although runtime downloading is possible. There are a number of characteristics of a Tone Signal Definition.
Signal ID
Tones definitions are identified by a Signal ID. This is a 32 bit number which is used to reference all tone signals once they have been downloaded (created). It is made up of the following fields:
Name:	Environment : Domain : Reserved : Category : Sub-Category : ID
Bits	       30-31	     20-29       17-19         9-16              5-8             0-4  

	Environment - The environment where the tone is used. e.g. Central Office, PBX, User Defined.
	Domain - Country code when used in the CO environment. It is partitioned into two 5 bit fields, each of which 	represent a letter of the ISO standard country code where the value 1 stands for the letter 'A'.
	Reserved - The reserved fields are used to define variants from the standard tones. If, for example, there were 	slight differences in the level requirements on two different front ends serviced by the same Tone generator,  then 	two tone signals would be defined with different values in this reserved field all other fields in the Signal Id 	identical. All bits should be set to 1 by default.
	Category - The class of the tone. e.g. BUSY, DIALTONE, DTMF, MF etc.
	Sub-Category - Qualifier to Category. e.g. R1 MF, R2 MF etc.
	ID - Finest resolution of Signal Id. e.g. DTMF 1, DTMF 2, etc.
Macros for building Signal Ids will be provided in a separate .H file.
Signal Label
A Signal Label is a user supplied ASCII string used to identify the tone. The string may be up to 4 characters in length. The Signal Label is used with the convenience MsgDial command to dial a string of predefined Tone Signals based on their Signal Labels. e.g. "1", or "BUSY".


Tone Segment Description(s)
Each Tone Signal consists of one or more Tone Segments. Each Tone Segment has the following characteristics:
	Signal Type - Tone Signals may be of many different Signal Types. e.g. silence, Single Tone, Dual Tone, AM 	Tone, Noise,	Impulse.
	Frequency - The frequency of each component of a tone signal is represented in Hertz.
	Amplitude - The amplitude of each frequency component of a tone signal is expressed in (0.25)dB units relative 	to the TLP0 	level.
	Duration - 	The On/Off duration of a tone signal is expressed in 125uSec units.
	Repitition Count - The number of times to play a tone segment.
	Next Segment - The next segment of a tone signal to play.	
5.2. Playing Tones
Once Tone Signals are created, they can be played in two ways:

	a)  There are the MsgPlayTone and MsgPlaySequence messages which allow a client to play a single or multiple 	Tone Signals based on Signal Id. These commands will play the prescribed Tone Signal(s) and return 	MsgPlayToneCmplt and MsgPlaySequenceCmplt messages respectively when the tones have been played.

	b)  There is a convenience MsgDial message which allows the client to specify a null-terminated ASCII string of 	Signal Labels. When the Tone Signals are played, the MsgDialCmplt is returned. This is the only time the Signal 	Labels are used in this Component.
5.4. Enabling Tone Sets
If for any reason there needs to be two different tone definitions of the a Tone Signal which has the same Signal Label present in one Tone Generator Component, the desired signal or set of signals may be selected using the ParmSignalSet parameter. 
This parameter is basically a Signal Id mask with the Environment, Domain and Reserved bit fields set to the appropriate values. 
For example, if a Tone Generator Component is connected to two different Network Interfaces with different DTMF tone characteristics, a client using the MsgDial command will still want to to dial DTMF's using the '1', '2', '3' etc labels and not have to worry about which Network he is connected to. To achieve, the client must do the following:
a) Create two sets of DTMF tones. Both sets with the same labels but the signal Ids will be different.
b) Enable the appropriate set by setting the ParmSignalSet parameter to the value of the Environment:Domain:Reserved:0:0 of the appropriate set of DTMF tone signal.
c) The MsgDial message will now play the correct DTMF tones when requested

5.5.	Run Time Control Actions
The following Run Time Control actions are supported:
RtcStop			Stop Playing Tones

6.	Message Set
The messages are defined using the Mercury Message Definition Language (MDL) with accompanying written descriptions.
The output header file from this message description will be TGENDEFS.H

.file	"tgendefs.h"
.author	"Luke Kiernan"
.version	"Revision A0.8"

<< 
This file describes the list of  Mercury messages, parameters and equates supported by the Mercury Tone Generator Component and its Instances.
>>

The Mercury Kernel definitions.
.sysdefs	"mercdefs.ext"

The Standard Mercury Component definitions.
.predefs	"stddefs.ext"

For now we define the range for Tone Generator messages, parameters and error codes here. In future this may be automatically generated by the MMDL based on the Component Type.
.min	.message	0x0500
.max	.message	0x05FF
.min	.parameter	0x0500
.max	.parameter	0x05FF
.min	.error		0x0500
.max	.error		0x05FF

<<
Include Signal Id definition file
>>
<
#include "sdsignal.h"
>

<<
Tone Generator Component Definition
>>
.component	Tgen = 0x05
{
<<
The Std_VendofID attribute will be set to Dialogic.
The Tone Generator uses messages from the Standard Kernel Message Set, the Standard Component Message Set and the Standard Waveform Generator Component Message Set.
>>
.uses
{
	<<
	Mercury Kernel Standard Message Set defined in mercdefs.doc
	>>
	<<
	Standard Component Message Set defined in stddefs.doc.
	>>
	<<
	Waveform Generator Component Message Set defined in wavegen.doc
	>>
	<<
	Waveform Generator Component Type used when trying to allocate a Waveform Generator Instance (TBD)
	>>
}

<< 
Tone Generator Message Definitions
>>
.defines
{	

6.1.	MsgCreateTone

. message .in		MsgCreateTone
{
	.uint32	SignalId
	.uint32	SegCount
	.uint8	SignalLabel[4]
	.varstart
	.struct	segs
	{
		.uint16	SignalType 
		.uint16	Freq1		<< {0:4000} >>
		.int16	Amp1		<< {-128:127} >>
		.uint16	Freq2		<< {0:4000} >>
		.int16	Amp2		<< {-128:127} >>
		.uint32	OnDuration	<< {0:4800000} >>
		.uint32	OffDuration	<< {0:4800000} >>
		.uint16	Reps		<< {0:65535} >>
		.int32	NextSeg		<< {-31:1} >>
	}
}
n Description - Command
<<
The MsgCreateTone message is sent to create a tone signal consisting of one or more tone segments.
SignalId	-	identifier for one complete tone. This must be unique for all instances.
SegCount	-	number of segments describing this tone.
SignalLabel	-	an optional four character string identifier for each tone template.
SignalType	-	type of signal to be generated. See Section 5.1 for explanation.
>>

<
#define	Tgen_MAXNUMSEGS    4
#define	Tgen_MAXLABELSIZE  4
>
<
#define	SigType_Singletone	0x1
#define	SigType_Dualtone	0x2
#define	SigType_AMTone	0x3
#define	SigType_Noise	0x4
#define	SigType_Impulse	0x5
#define	SigType_Silence	0x6
>
<
#define	Tgen_AddToneSeg_EOS	0xffff
>
<<
Freq1	-	frequency of first component of tone. (units Hz)
Amp1	-	amplitude of first component of tone. (units 0.25 dB relative to TLP0)
Freq2	-	frequency of second component of tone. (units Hz)
Amp2	-	amplitude of second component of tone. (units 0.25 dB relative to TLP0)
OnDuration	-	duration of tone (units 0.125 msecs, 0 means play tone continuously)
OffDuration	-	duration of silence (units 0.125 msecs, 0 means play silence continuously).
Reps	-	number of repititions for segment. 0 means play segment continuously.
NextSeg	-	relative number of next segment. 0 means play segment continuously. Tgen_AddToneSeg_EOS means last segment.
>>

The following is a detailed description of the types of signal that may be generated using the Tone Generator.
SignalType = SILENCE: 
This directs the Tone Generator to produce the specified period of  silence.
Freq1, Ampl1, Freq2, Ampl2, and OnDuration are not used (must be set to zero).
OffDuration (Silence Duration) specifies how long (units of 125(S) to generate silence.  
Reps field specifies how many repetitions of this silence interval should be generated.
SignalType = SINGLETONE: 
This directs the Tone Generator to produce the specified period of  'pure' tone optionally followed by some period of silence.
Ampl1is a dB number (in units 0f 0.25dB) relative to TLP0.  Thus Amplitude = -8 directs the Waveform Generator to produce a sinusoid whose peak power is -2dBm (8 * 0.25) at TLP0.
Freq1 is an integer that specifies the frequency of the sinusoid in Hertz.
Ampl2 and Freq2 are not used (must be set to zero).
OnDuration specifies how long (units of 125(S) to generate the single tone.
OffDuration specifies how much silence (units of 125(S) should be generated following the single tone.  
Reps specifies how many times of this tone/silence segment should be generated.  A SegmentRepetitionCount of 1 says "play the tone for TDuration samples, followed by silence for SDuration samples, and then proceed to next tone segment descriptor."
SignalType = DUALTONE: 
This directs the Tone Generator to produce the specified period of  tone consisting of the sum of two sinusoids optionally followed by some period of silence.
Ampl1 is a dBm number (in units of 0.25dBm) relative to TLP0 for the first sinusoid component.  Thus Ampl1 = +2 directs the Tone Generator to produce a sinusoidal component whose peak amplitude is 0.5dBm at TLP0.
Freq1 is an integer that specifies the frequency of the first sinusoid component  in Hertz.
Ampl2 is a dBm number (in units of 0.25dBm) relative to TLP0 for the second sinusoid component.  Thus Ampl2 = -6 directs the Tone Generator to produce a sinusoidal component whose peak amplitude is -1.5dBm at TLP0.
Freq2 is an integer that specifies the frequency of the second sinusoid component  in Hertz.
OnDuration specifies how long (in units of 125(S) to generate the two summed sinusoids.
OffDuration parameter specifies how much silence (in units of 125(S) should be generated following the dual tone.
Reps specifies how many repetitions of this tone/silence segment should be generated.
Example: Generation of a DTMF digit '*'
SignalType=DUALTONE
Ampl1=12
Freq1=941
Ampl2=12
Freq2=1209
OnDuration=400
OffDuration=400
Reps=1
NextSeg=0
This Tone Signal Descriptor produces one DTMF '*' digit with zero twist, each sinusoidal component 3dBm at TLP0, an 'on' time of 50mS followed by an 'off' time of 50mS.
SignalType = AMTONE: 
This directs the Tone Generator to produce the specified period of tone consisting of the product of two sinusoids (a double-sideband, suppressed-carrier, AM signal) optionally followed by some period of silence.
Ampl1is a dBm number (in units of 0.25dBm) relative to TLP0 that specifies peak amplitude of the first sinusoidal component (the carrier). Thus Ampl1 = -24 directs the Tone Generator to produce a sinusoidal component whose peak amplitude is -6dBm at TLP0.
Freq1is an integer that specifies the frequency of the first sinusoid component  in Hertz.
Ampl2 is not used and should be set to zero.  The modulation index is fixed at 100%.
Note that the peak amplitude of a DSB-SC AM signal is the product of the peak amplitude of the carrier and the modulator. 
Freq2 is an integer that specifies the frequency of the second sinusoid component (the modulator) in Hertz.
OnDuration specifies how long (in units of 125(S) to generate the DSB AM signal.
OffDuration specifies how much silence (in units of 125(S) should be generated following the DSB AM tone.
Reps specifies how many repetitions of this tone/silence segment should be generated.
Example: Generation of the Brunei Darussalam dial tone
SignalType=AMTONE
Ampl1=0
Freq1=400
Ampl2=0		/* not used */
Freq2=50
OnDuration=960000
OffDuration=0
Reps=1
The MSD above produces the Brunei Darussalam dial tone which consists of a 400Hz tone AM modulated by a 50Hz tone.  By setting the amplitude of the carrier to 0dBm at TLP0 (specified by Ampl1) the resulting signal has a peak amplitude of 0dBm measured at TLP0.  The tone lasts a maximum of 2 minutes.  It would normally be terminated prior to this by a MsgStop message.
SignalType = NOISE: 
This directs the Tone Generator to produce the specified period of tone consisting of noise optionally followed by some period of silence.
Ampl1is a dBm number (in units of 0.25dBm) relative to TLP0 that specifies peak amplitude of the noise.
Freq1, Ampl1 and Freq2 are not used.  They must be set to zero.
OnDuration parameter specifies how much noise (in units of 125(S) to generated.
OffDuration parameter specifies how much silence (in units of 125(S) should be generated following the noise.
Reps specifies how many repetitions of this noise/silence segment should be generated.
SignalType = IMPULSE: 
This directs the Tone Generator to produce the specified interval 'DC' signal (at the level specified by Ampl1) typically followed by some period of silence.  By setting OnDuration to '1' and the OffDuration to >> '1' an impulse train may be produced.
Ampl1is a dBm number (in units of 0.25dBm) relative to TLP0 that specifies the amplitude of the signal.
Freq1, Ampl2 and Freq2 are not used.  They must be set to zero.
OnDuration specifies how many long (in units of 125(S) to generate the signal of Ampl1.
OffDuration specifies how much silence (in units of 125(S) should be generated following the non-zero signal.
Reps specifies how many repetitions of this 'on'/'off' segment should be generated.
Example#1: DC-offset square wave
SignalType=IMPULSE
Ampl1=0
Freq1=0
Ampl2=0
Freq2=0
OnDuration=128
OffDuration=128
Reps=1000
produces an offset square wave of amplitude of 0dBm at TLP0 with a 50% duty cycle, a period of 32mS (128 * 125(S = 16mS 'on, and 128 * 125(S = 16mS 'off') repeated 1000 times.
Example#2: impulse train 
SignalType=IMPULSE
Ampl1=40
Freq1A=0
Ampl2=0
Freq2=0
OnDuration=1
OffDuration=1023
Reps=256
The above Tone Signal Definition produces 256 impulses, each of amplitude 10dBm at TLP0 and each followed by a period of silence of approximately 128mS.  This might be used to examine impulse response.

n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

ErrSignalType
Invalid Signal type. Signal type will be returned in Std_MsgError message.

ErrFrequency
Invalid frequency specified. Frequency and tone segment where error occured will be returned in Std_MsgError message.

ErrAmplitude
Invalid amplitude specified. Amplitude and tone segment where error occured will be returned in Std_MsgError message.

ErrDuration
Invalid duration. Duration and tone segment where error occured will be returned in Std_MsgError message.

ErrNextSeg
Invalid next segment. Segment and tone segment where error occured will be returned in Std_MsgError message.

ErrMaxSignals
Maximum number of tone signals already created.

n Related Messages
MsgCreateToneCmplt, MsgDeleteTone
n Cautions
None.

6.2.	MsgCreateToneCmplt

. message .out	MsgCreateToneCmplt
n Description - Response
<<
The MsgCreateToneCmplt message is sent as a response to the MsgCreateTone command when the specified tone signal been created. 
 >>
n Errors
None.
n Related Messages
MsgCreateTone
n Cautions
None.

6.3.	MsgDeleteTone

. message .in		MsgDeleteTone
{
	.uint32	SignalId
 }
n Description - Command
<<
The MsgDeleteTone message is sent to delete a tone signal.
SignalId	-	Signal Id to delete.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

ErrSignalId
Invalid SignalId. Signal Id will be returned in Std_MsgError message.

n Related Messages
MsgDeleteToneCmplt, MsgCreateTone
n Cautions
A tone signal may not be deleted if it is currently being played.

6.4.	MsgDeleteToneCmplt

. message .out	MsgDeleteToneCmplt

n Description - Response
<<
The MsgDeleteToneCmplt message is sent as a response to the MsgDeleteTone command when the specified tone signal has been deleted. 
 >>
n Errors
None.
n Related Messages
MsgDeleteTone
n Cautions
None.

6.5.	MsgPlayTone

. message .in		MsgPlayTone
{
	.uint32	SignalId
 }

n Description - Command
<<
The MsgPlayTone message is sent to start playing a tone signal.
SignalId	-	signal Id of tone signals to play.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

ErrSignalId
Invalid SignalID. Signal Id will be returned in Std_MsgError message.

n Related Messages
MsgPlayToneCmplt, MsgStop 
n Cautions
None.


6.6.	MsgPlayToneCmplt

. message .out	MsgPlayToneCmplt
{
	.uint32	Reason { EOD = 1, UserStop = 2, Rtc = 3 }
	.uint32	RtcLabel
}
n Description - Response
<<
The MsgPlayToneCmplt message is sent as a response to the MsgPlayTone command when playback of the specified tone signal has completed. 
Reason	-	reason for stopping.
RtcLabel	-	if Reason is Rtc then this is the EventLabel of the event which caused the playing of the tone to stop.
 >>
n Errors
None.
n Related Messages
MsgPlayTone
n Cautions
None.

6.7.	MsgPlaySequence

. message .in		MsgPlaySequence
{
	.uint32	Count
	.varstart
	.mbuf	List
	{
		.uint32	SignalId
	}
 }
n Description - Command
<<
The MsgPlaySequence message is sent to play a sequence of tone signals.
Count	-	number of tone signals to play.
Id	-	signal Ids of tone signals to play.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

ErrSignalId
Invalid SignalID

n Related Messages
MsgPlaySequenceCmplt, MsgStop 
n Cautions
None.


6.8.	MsgPlaySequenceCmplt

. message .out	MsgPlaySequenceCmplt
{
	.uint32	Reason { EOD = 1, UserStop = 2, Rtc = 3 }
	.uint32	RtcLabel
}
n Description - Response
<<
The MsgPlaySequenceCmplt message is sent as a response to the MsgPlaySequence command when playback of the specified sequence of tone signals has completed. 
Reason	-	reason for stopping.
RtcLabel	-	if Reason is Rtc then this is the EventLabel of the event which caused the playing of the tone to stop.
 >>
n Errors
None.
n Related Messages
MsgPlaySequence
n Cautions
None.

6.9.	MsgDial

. message .in		MsgDial
{
	.uint8	Count
	.varstart
	.mbuf	String
	{
		.uint8	Character
	}
}
n Description - Command
<<
The MsgDial message is sent to start playing a string of tones defined by a null terminated ASCII string. The characters in the string are the labels of the predefined tones and are separated by a white space. The ParmSignalSet is used to decide which tone signal to play if two tone signals have the same Signal Label.
Count	- 	The total number Char's in the string including the NULL.
Character	-	character of label to play.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

Err_InvLabel
Invalid label defined in dial string.

Err_MultiLabel
Multiple descriptions of the same Label enabled

n Related Messages
MsgDialCmplt, MsgStop 
n Cautions
If a string contains an unrecognizable label then none of the string will be dialed and a Std_MsgError returned.
If a label matches more than one Tone Signal Description even after masking with the ParmSignalSet parameter then none of the string will be dialed and a Std_MsgError returned.

6.10.	MsgDialCmplt

. message .out	MsgDialCmplt
{
	.uint32	Reason { EOD = 1, UserStop = 2, Rtc = 3 }
	.uint32	RtcLabel
}
n Description - Response
<<
The MsgDialCmplt message is sent as a response to the MsgDial command when playback of the specified string of tones has completed. 
Reason	-	reason for stopping.
RtcLabel	-	if Reason is Rtc then this is the EventLabel of the event which caused the playing of the tone to stop.
 >>
n Errors
None.
n Related Messages
MsgDial, MsgStop
n Cautions
None.

6.11.	MsgStop
 
. message .in		MsgStop
n Description - Command
<<
The MsgStop message is sent to stop whatever play function is active in the Tone Generator.
>>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is idle or preallocated then this error is returned.

n Related Messages
MsgPlayToneCmplt, MsgPlaySequenceCmplt, MsgDialCmplt
n Cautions
None.

6.12.  WgenInfo

. message .in		MsgWgenInfo
n Description - Command
<<
A request to get the wave generator address associated with a tone generator instance
>>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is idle or preallocated then this error is returned.

n Related Messages
WgenInfoCmplt
n Cautions
None.

6.13.	WgenInfoCmplt

. message .out		MsgWgenInfoCmplt
{
	.uint8		Node
	.uint8		Board
	.uint8		Processor
	.uint8		Component
	.uint8		Instance
	.uint24		PCMcoding
	.uint24		streamID
}

n Description - Command
<<
Returns the actual wave generator address associated with an instance of the tone generator.  Sent in response to a WgenInfo message.
>>
n Errors
None
n Related Messages
WgenInfo
n Cautions
None.


6.14.	R2MFSet
. message .in		MsgR2MFSet
n Description - Command
<<
A request to get the wave generator ID's associated with the R2MF forward and backward sets
>>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is idle or preallocated then this error is returned.

n Related Messages
R2MFSetCmplt
n Cautions
None.


6.15.	R2MFSetCmplt
. message .out		MsgR2MFSetCmplt
{
	.uint8	Forward[16]
	.uint8	Backward[16]
}

n Description - Command
<<
Returns the actual wave generator ID's associated with the R2MF set.  Sent in response to a R2MFSet message.
>>
n Errors
None
n Related Messages
R2MFSet
n Cautions
None.


6.16.	MsgDialx

. message .in		MsgDialx
{
	.uint8	Count
	.uint8	ParmCount
	.varstart
	.mbuf	String
	{
		.uint8	Character
	}
	.struct	ParmList	
	{ 
		.parameter	Num
		.uint32	Val
	}
}
n Description - Command
<<
The MsgDial message is sent to set a list of parameters and, then, start playing a string of tones defined by a null terminated ASCII string. The characters in the string are the labels of the predefined tones and are separated by a white space. The ParmSignalSet is used to decide which tone signal to play if two tone signals have the same Signal Label.
Count	- 	The total number Characters in the string including the NULL.
Character	-	character of label to play.
ParmCount	-	The number of parameters to be set.
ParmList	-	The key/value pairs of the parameters to be set.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

Std_ErrParmNum
Invalid parameter number.
	
Std_ErrParmReadOnly
A read-only parameter was specified to be set.

Err_InvLabel
Invalid label defined in dial string.

Err_MultiLabel
Multiple descriptions of the same Label enabled

n Related Messages
MsgDialCmplt, MsgStop 
n Cautions
If a string contains an unrecognizable label then none of the string will be dialed and a Std_MsgError returned.
If a label matches more than one Tone Signal Description even after masking with the ParmSignalSet parameter then none of the string will be dialed and a Std_MsgError returned.

6.17.	MsgPlayTonex

. message .in		MsgPlayTonex
{
	.uint32	SignalId
	.uint8	ParmCount
	.varstart
	.struct	ParmList	
	{ 
		.parameter	Num
		.uint32	Val
	}
 }

n Description - Command
<<
The MsgPlayTone message is sent to set a list of parameters and, then, start playing a tone signal.
SignalId	-	signal Id of tone signals to play.
ParmCount	-	The number of parameters to be set.
ParmList	-	The key/value pairs of the parameters to be set.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

Std_ErrParmNum
Invalid parameter number.
	
Std_ErrParmReadOnly
A read-only parameter was specified to be set.

ErrSignalId
Invalid SignalID. Signal Id will be returned in Std_MsgError message.

n Related Messages
MsgPlayToneCmplt, MsgStop 
n Cautions
None.

6.18.	MsgPlaySequencex

. message .in		MsgPlaySequencex
{
	.uint32	Count
	.uint8	ParmCount
	.varstart
	.mbuf	List
	{
		.uint32	SignalId
	}
	.struct	ParmList	
	{ 
		.parameter	Num
		.uint32	Val
	}
 }
n Description - Command
<<
The MsgPlaySequence message is sent to set a list of parameters and, then, play a sequence of tone signals.
Count	-	number of tone signals to play.
Id	-	signal Ids of tone signals to play.
ParmCount	-	The number of parameters to be set.
ParmList	-	The key/value pairs of the parameters to be set.
 >>
n Errors
If an error occurs in the execution of the command then a Std_MsgError message will be sent in place of the command's response message.
The following errors may be returned as a Std_MsgError:

Error
Description

Std_ErrSystem
System error. 

Std_ErrBusy
Busy executing previous command.

Std_ErrUnexpectedMsg
Unexpected message. If Tone Generator state is not idle then this error is returned.

Std_ErrParmNum
Invalid parameter number.
	
Std_ErrParmReadOnly
A read-only parameter was specified to be set.

ErrSignalId
Invalid SignalID

n Related Messages
MsgPlaySequenceCmplt, MsgStop 
n Cautions
None.
7.	Parameters
The following is a list of parameters for the Mercury Tone Generator Component. 

Parameter access is classified as read only (R), write only (W) and as read/write (R/W).

Parameter level is classified as Component (C), Instance (I), or Component and Instance (C/I).

<< 
Tone Generator Parameter Definitions
>>

Parameter type and name
Access
Level
Description
.parameter .uint32 ParmTLP0
R/W
C
<<
Default playback level of tones. (absolute)
>>
.parameter .uint32 ParmSignalSet
R/W
C/I
<<
When two or more  signalId's map to the same  ASCII label's this parameter is used to resolve the difference for all operations involving the label such as MsgDial.   if only one  signal Id is found with this label then this parameter is not relevant, that Id will always be used.  By default the DTMF set is used.
>>
.parameter .uint32 ParmMaxSignalIds
R/W
C
{def=128}
<<
Maximum number of tone template definitions that may be defined  for generation.  The maximum is 256 templates.
>>
.parameter .uint32 ParmMaxSeqLen
R/W
C
<<
The maximum number of tones for one play sequence or dial message.  The maximum and default value is 40.
>>



8.	Error Codes 
The following is a list of error codes for the Mercury Tone Generator Component. They are returned in the Errorcode field of the Std_MsgError message.
<< 
Tone Generator Error Code Definitions
>>
Error name
Description
.error ErrSignalId

<<
Invalid SignalId specified. Signal Id specified in Val field in error message. See below.
>>
.error ErrSignalType

<<
Invalid Signal type. Signal Type in Val field in error message. See below.
>>
.error ErrFrequency

<<
Invalid frequency specified. Frequency in Val field in error message. Segment where error occured in Seg field in error message. See below.
>>
.error ErrAmplitude

<<
Invalid amplitude specified. Amplitude in Val field in error message. Segment where error occured in Seg field in error message. See below
>>
.error ErrNextSeg

<<
Invalid next segment specified. Segmane in Val field in error message. Segment where error occured in Seg field in error message. See below.
>>
.error ErrInvLabel
.message! DialErr
{
    .uint32 Msg
    .uint32 Code
    .uint8 Label[4]
}
<<
Invalid label defined in dial string.
>>
.error ErrMultiLabel
<<
Multiple tone signals with the same label enabled. Error message in DialErr format.
>>
.error ErrBadTSD
<<
The segment described in a create tone message was invalid
>>
.error ErrMaxSignals
<<
Maximum number of tone signals already creared.
>>

<<
Error message format
>>
.message! Err
{
    .uint32 Msg
    .uint32 Code
    .uint32 Val
    .uint32 Seg
}
9. Attributes
The following are the values of the attrributes for the Mercury Tone Generator Component.

<<
Standard Attribute Definitions
>>

Attribute name
Description
.external .attribute Std_ComponentType {Std_ComponentType = 0x05}
<<
Component Type Defintion.
>>




<<
Mercury Tone Generator Specific Attributes
>>

Attribute name
Description





10.	Event Types
The following is a list of Event types for the Mercury Tone Generator Component. They are supported by the Mercury Tone Generator Component and its Instances. They may ALL be used as conditions for Run Time Control. When enabled, these events are sent to the Component specified in the ReturnAddress field of the Std_MsgDetectEvt message. They are sent using the Std_MsgEvtDetected message.
Some of these messages return extra data as part of the message. This extra data may be ignored if these events are used for Run Time Control.

<< 
Tone Generator Event Type Definitions. 
>>
.message!	Event
{
	.compdesc	ReturnAddress
	.uint32	Type	{EvtStarted, EvtStopped}
	.uint32	Label
}

Event name
Description
EvtStarted
<<
EvtStarted is generated when a tone starts playing.
>>
.message! EvtStopped
{
    .uint32 EventLabel
    .uint32 Reason { EOD = 1, UserStop = 2, Rtc = 3 }
    .uint32 RtcLabel
}
<<
EvtStopped is generated when playback of a tone or sequence of tones has stopped. The reason for stopping is in the data field of the message.
>>


11.	RTC Actions
The following is a list of Run Time Control Actions for the Mercury Tone Generator Component. They are supported by the Mercury Tone Generator Component and its Instances.
These RTC Actions are enabled using the Std_MsgArmRTC or Std_MsgArmxRTCs messages.
All RTC Actions are ignored if the Tone Generator is in an invalid state e.g. RtcPause will be ignored if Tone Generator is already paused.

<< 
Tone Generator Run Time Control Actions Definitions
>>
.message!	Action
{
	.uint32	Label
	.uint32	Type	{ RtcStop }
}

RTC Action name
Description
RtcStop
<<
RtcStop is a RTC Action to stop playback of a tone or tone sequence.
>>
12. Miscellaneous Equates
<
/* Tgen_MsgDial_String_varStart is defined to avoid possible 
   backwards compatibility issues */
#define Tgen_MsgDial_String_varStart  Tgen_MsgDial_varStart
>
<<
End of all Mercury Tone Generator Component Definitions
>>
}
}
Mercury Tone Generator Component Interface Specification - Revision A0.8
SWS-0225


DIALOGIC CONFIDENTIAL
45 of 45

