You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > Tone Configure 0x0031

Tone Configure 0x0031

SwitchKit Name

TransmitToneConfig

Type

EXS API and SwitchKit API message

Description

Tone Configure 0x0031

This message is used to configure a transmit tone or call progress receive tone. If the host duplicates transmit tones in the system, it is only necessary to do so once per DSP card.

For more information on customizing tones and patterns, refer to the API Developer’s Guide: Overview, Adjusting Attributes of Call Progress Tones.

Sent by

Host

SwitchKit Code

Configuration

TransmitToneConfig (

Node = integer,

UpdateFlag = integer,

Reserved = integer,

ToneType = integer,

Action = integer,

Data = byte array);

C Structure

typedef struct {

UBYTE UpdateFlag;

UBYTE Reserved;

UBYTE ToneType;

UBYTE Action;

UBYTE Data[249];

} XL_TransmitToneConfig;

C++ Class

class XLC_TransmitToneConfig : public XLC_OutboundMessage {

public:

UBYTE getUpdateFlag() const;

void setUpdateFlag(UBYTE x);

UBYTE getReserved() const;

void setReserved(UBYTE x);

UBYTE getToneType() const;

void setToneType(UBYTE x);

UBYTE getAction() const;

void setAction(UBYTE x);

const UBYTE *getData() const;

UBYTE *getData();

void setData(UBYTE *x);

};

Overview of message

The following table provides an overview of this message. The table following it provides the detail for each byte.

MESSAGE (White) | RESPONSE (Gray)
Byte | Field Description | Byte | Field Description
0 | Frame (0xFE) | 0 | Frame (0xFE)
1, 2 | Length (0xNNNN) | 1, 2 | Length (0x0007)
3, 4 | Message Type (0x0031) | 3, 4 | Message Type (0x0031)
5 | Reserved (0x00) | 5 | Reserved (0x00)
6 | Sequence Number | 6 | Same Sequence Number
7 | Logical Node ID | 7 | Logical Node ID
8, 9 | Status MSB, LSB
10 | Checksum
8 | Update All Flag
9 | Reserved
10 | Tone Type
11 | Action
12 | Data[0]
: | Checksum

EXS API Hex Format - Detailed

MESSAGE (White) | RESPONSE (Gray)
Byte | Field Description | Byte | Field Description
0 | Frame (0xFE) | 0 | Frame (0xFE)
1, 2 | Length (0x00NN) | 1, 2 | Length (0x0007)
3, 4 | Message Type (0x0031) | 3, 4 | Message Type (0x0031)
5 | Reserved (0x00) | 5 | Reserved (0x00)
6 | Sequence Number | 6 | Same Sequence Number
7 | Logical Node ID | 7 | Logical Node ID
8, 9 | Status MSB (0x00) Status LSB: 0x01 Maximum frequencies per tone exceeded. This response is returned if the Frequency Counter in the Tone Configure message exceeds two. 0x02 Maximum frequencies per tone group exceeded. This response is returned if the number of frequencies in the Tone Group exceeds 16 (including possible new frequencies in the Tone Configure message. 0x03 Invalid frequency. This response is returned if any frequency in the Tone Configure message exceeds the theoretical limit (4000 Hz).
10 | Checksum
8 | Update All Flag A configuration is "engaged" when it is used when the tone is transmitted. 0x00 Store configuration but do not engage it. This is the normal case for large configuration of parameters. Configuration will not be engaged until another message has this bit set to 1. 0x01 Engage configuration immediately This is usually set for the last configuration message so configuration engaging takes place only once and for all of the new configuration previously sent.
9 | Reserved
10 | Tone Type 0x01 Call Progress Transmit Tones 0x02 DTMF Transmit Tones 0x03 MFR1 Transmit Tones 0x04 MFR2 Forward Transmit Tones 0x05 MFR2 Backward Transmit Tones 0x06 Call Progress Receive Tones
11 | Action 0x01 Configure Call Progress Tones 0x02 Reserved 0x03 Global Update of dBm levels (Tone Types 2–5)
12 | Data[0] The value of the Data fields is dependent on the value of the Action field. 0x01 Configure Call Progress Tones The following data uniquely identifies an existing tone or a new tone. All values must be entered redefining that tone if it exists already. The maximum number of frequencies per tone is limited to the DSP load configured to play the tone (2 or 4). Caution! Changing this tone changes every tone pattern referencing this tone. Data[0] Tone ID being changed Data[1] Reserved Data[2] Number of Frequencies making up tone (1 or 2 for receive tone) Data[3] Reserved Data[4] Frequency Value[0] Hz, MSB Data[5] Frequency Value[0] Hz, LSB Data[6] Frequency dBm[0], MSB - must be 0 for call progress receive tones (0x06). For call progress transmit tones (0x01), specify power level. Data[7] Frequency dBm[0], LSB : Data[n++] Frequency Value[n] Hz, MSB Data[n++] Frequency Value[n] Hz, LSB Data[n++] Frequency dBm[n], MSB Data[n++] Frequency dBm[n], LSB 0x02 Reserved 0x03 Global Update of dBm Level This action changes the power level of the transmit tones of the specified type. The update affects all tone generators of the specified type in the system. For Tone Type 2 (DTMF) the dBm level for both low-band and high-band frequency components must be specified. The other Tone Types require only one dBm level to be specified. The default dBm levels are as follows: DTMF (low-band) -4.0 dBm DTMF (high-band) -4.0 dBm MFR1 -7.0 dBm MFR2 (forward) -9.0 dBm MFR2 (backward) -9.0 dBm Data for Tone Type 2 Data[0] dBm level for low-band frequency component, MSB Data[1] dBm level for low-band frequency component, LSB Data[2] dBm level for high-band frequency component, MSB Data[3] dBm level for high-band frequency component, LSB Data for Tone Types 3–5 Data[0] dBm level, MSB Data[1] dBm level, LSB
: | Checksum

Example Message—Global Update of dBm Level

The following is an example using the Tone Configure message to change the power levels of DTMF tones to: -4 dBm for low-band frequency, and -7 dBm for high-band frequency.

Byte | Message | Value
0 | Message Frame | 0xFE
1 | Length, MSB | 0x00
2 | Length, LSB | 0x0D
3 | Message Type, MSB | 0x00
4 | Message Type, LSB | 0x31
5 | Reserved | 0x00
6 | Sequence Number | SN
7 | Logical Node ID | 0xFF
8 | Update All Flag | 0x01
9 | Reserved | 0x00
10 | Tone Type | 0x02
11 | Action | 0x03
12 | Data[0]: dBm level for low-band frequency component, MSB | 0xFF
13 | Data[1]: dBm level for low-band frequency component, LSB | 0xFC
14 | Data[2]: dBm level for high-band frequency component, MSB | 0xFF
15 | Data[3]: dBm level for high-band frequency component, LSB | 0xF9
16 | Checksum | CS

Example Message—Configure Tone

The following example shows the message contents that would be sent to configure a specific tone to be outpulsed.

Configure Tone: Tone ID Number 4 (2 Frequencies: 440Hz, -13dBm; 480Hz, -13dBm)

Byte | Message | Value
0 | Message Frame | 0xFE
1, 2 | Length | 0x0015
3, 4 | Message Type | 0x0031
5 | Reserved | 0x00
6 | Sequence Number | SN
7 | Logical Node ID | 0xFF
8 | Update All Flag | 0x01
9 | Reserved | 0x00
10 | Tone Type | 0x01
11 | Action | 0x01
12 | Data[0]: Tone ID being changed | 0x04
13 | Data[1]: Reserved | 0x00
14 | Data[2]: Number of frequencies making up tone | 0x02
15 | Data[3]: Reserved | 0xF9
16 | Data[4]: Frequency Value[0] Hz, MSB | 0x01
17 | Data[5]: Frequency Value[0] Hz, LSB | 0xB8
18 | Data[6]: Frequency dBm[0], MSB | 0xFF
19 | Data[7]: Frequency dBm[0], LSB | 0xF3
20 | Data[8]: Frequency Value[1], Hz MSB | 0x01
21 | Data[9]: Frequency Value[1] Hz, LSB | 0xE0
22 | Data[10]: Frequency dBm[1], MSB | 0xFF
23 | Data[11]: Frequency dBm[1], LSB | 0xF3
24 | Checksum | CS

Configuring a Sample Pattern ID

The following example shows how to configure Pattern ID 0x17 to receive a three-second, 400 Hz tone. To perform this task, the host sends three API messages. First, the host sends the Tone Configure message to replace the default tone (Tone ID 0x0F, 425 Hz) with the new, 400 Hz tone. Second, the host sends the CPA Pattern Configure message to create the new Pattern ID 0x17. Third, the host sends the CPA Class Configure message to add Pattern 0x17 to the CPA class 0x00.

First Message: Tone Configure

Byte | Field Description
0 | Message Frame 0xFE
1,2 | Length (2 bytes) 0x0011
3,4 | Message Type (2 bytes) 0x0031
5 | Reserved 0x00
6 | Sequence Number
7 | Logical Node ID 0xFF
8 | Update All Flag 0x01
9 | Reserved 0x00
10 | Tone Type 0x06
11 | Action 0x01
12 | Data[0] Tone ID being changed 0x0F
13 | Data[1] Reserved 0x00
14 | Data[2] Number of frequencies in tone 0x01
15 | Data[3] Reserved 0x00
16 | Data[4] Frequency Value[0], Hz, MSB 0x01
17 | Data[5] Frequency Value[0], Hz, LSB 0x90
18 | Data[6] Reserved 0x00
19 | Data[7] Reserved 0x00
20 | Checksum

Second Message: Call Progress Analysis Pattern Configure

Byte | Field Description
0 | Message Frame 0xFE
1,2 | Length (2 bytes) 0x0016
3,4 | Message Type (2 bytes) 0x00B2
5 | Reserved 0x00
6 | Sequence Number
7 | Logical Node ID 0xFF
8 | Update All Flag 0x01
9 | Pattern ID 0x17
10 | Action: Add/Replace Pattern 0x01
11 | Data[0] Pattern ID to report on detection 0x17
12 | Data[1] Tone Group ID 0x00
13 | Data[2] Pattern Configuration 0x01
14 | Data[3] CPA Report on Pattern Loss 0x17
15 | Data[4] Interval Cycles to Match 0x01
16 | Data[5] Interval Cycles to Report 0x01
17 | Data[6] Reserved 0x00
18 | Data[7] Interval Descriptor Count 0x01
19 | Data[8] Tone ID 0x0F
20 | Data[9] Reserved 0x00
21 | Data[10] Minimum filter (in 10 ms units) MSB 0x00
22 | Data[11] Minimum filter (in 10 ms units) LSB 0x50
23 | Data[12] Maximum filter (in 10 ms units) MSB 0x00
24 | Data[13] Maximum filter (in 10 ms units) LSB 0x00
25 | Checksum

Third Message: Call Progress Analysis Class Configure

Byte | Field Description
0 | Message Frame 0xFE
1,2 | Length (2 bytes) 0x0009
3,4 | Message Type (2 bytes) 0x00B3
5 | Reserved 0x00
6 | Sequence Number
7 | Logical Node ID 0xFF
8 | Update All Flag 0x01
9 | Class ID 0x00
10 | Action 0x01
11 | Data[0] Pattern ID 0x17
12 | Checksum

Digital Signal Processor
A computer, attached to the Excel platform through an RS-232 or Ethernet link, from which you run the telecommunications application that controls the Excel platform.
A group of data bits in a specific format, with a flag at each end to indicate the beginning and the end of the frame.
Most Significant Bit
Least Significant Bit
Message delimiter (SS7 bit pattern - 01111110)
Hertz