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

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