Introduction to API Messages

Overview

Messages and Responses

Messages and Responses each contain a header and a checksum, and can also contain AIBs (Address Information Blocks), ICBs (Information Control Blocks), TLVs (Tag-Length-Value blocks), and data.

Data

Data can reside in its own Data field or within AIBs, ICBs, or TLVs.

Field

A Field corresponds to a single row in the main Message/Response table, and it can be either one byte (for example 0x1B) or two bytes long (for example 0x1B4D). In accordance with Big Endian formatting, when a field is two bytes long, the first byte (in this case 0x1B) is the Most Significant Byte (MSB) and the second byte (in this case 0x4D) is the Least Significant Byte (LSB).

The next figure, EXS API Message / Response Table, provides an overview of API messages and refers to the chapters containing the specific information.

Figure 1-1

EXS API Message / Response Table

Generic API Message Format

API messages and responses are frames, containing strings of paired characters. The characters are represented in hexadecimal notation. Each frame consists of a standard header, followed by a variable number of data bytes. The data is unique to each message.

All messages, whether initiated by the Excel platform or by the host, must have a corresponding Response. The message fields are shown on the left (white) side of the table and the response fields are shown on the right (gray) side.

In this example, standard header information (bytes 0–) is indicated by the bold outline.

Field Descriptions

This section describes the fields in the header of each API message and response.

Frame

The first field in every message is always the Frame field. It is a one-byte value that indicates the beginning of the frame. The value 0xFE is reserved for this purpose alone.

Because the value 0xFE is reserved for the Frame field, you must never use this value in any other field. If you must send the value 0xFE within the contents of a message, you must encode it using an escape sequence.

Length

The second field is always the Length field. It is a value that indicates the number of bytes to follow, excluding the Checksum.

Important! The system calculates the message length before using an escape sequence. You must do the same.

To calculate the value of the Length field, count the bytes between, but not including, the Length field and the Checksum field. In the message below, the length is 5. You can see the value 5 in the second byte of the length field, represented in hexadecimal notation as 0x05.

Message Type

The third field is always the Message Type field. It is a value that identifies the format and particular information contained in the message or response.

Sequence Number

Use the Sequence Number field(s), Bytes 5 and 6, to match corresponding responses and messages. Because the EXS API protocol is asynchronous, the system may contain more than one outstanding message of the same type. When a response to one of these messages returns, the response would be useless if there were no way to trace it to its corresponding message.

The Sequence Number resolves this issue by initiating either an 8-bit or 16-bit sequence number in an EXS API message. The sender of the message (either the host or the Excel platform) assigns the sequence number.

To provide backward compatibility, the 16-bit sequence number is enabled using the Generic Card Configure 0x0122 message and can be queried using the Generic Card Query 0x0123 message. The Matrix/Host Sequence Number Size TLV (0x0640) is used to configure either the 8-bit or 16-bit sequence number.

• 8-Bit Sequence Number

An 8-bit sequence number in the Byte 6 field is the default configuration. In this configuration, the Byte 5 field should always be set to 0x00 in Excel platform and Host initiated messages. Any other value in this field is reset to 0x00 in the response message to the Host. An 8-bit sequence number is in the range of 0x00-0xFF.

• 16-bit Sequence Number

A 16-bit sequence number extends the 8-bit sequence number Byte 6 (LSB) field into the Byte 5 (MSB) field to create a 16-bit sequence number. A 16-bit sequence number will be in the range of
0x00-0xFFFF.

When the Matrix Controller card is configured to use the 16-bit sequence number, Bytes 5 and 6 will contain the sequence number for both Host and Excel platform-initiated messages.

• A 16-bit sequence number in a Host-initiated message will follow the message through the Excel platform and be returned in the response.

• A 16-bit sequence number in a Excel platform-initiated message will be passed to the Host and be expected in the Host response.

Important! The 16-bit Sequence Number does not support LAPD and EXNET Connect.

AIB

Address Information Blocks (AIBs) are used to address system objects such as slots, spans, and channels. An AIB can contain one or more Address Elements (AEs) to accommodate a variety of addressing requirements. An Address Element is a group of data bytes that represent specific address information.

Status

Most responses contain a Status field that follows the header. If the Excel platform processes a message successfully, it returns a positive acknowledgment (ACK) value of 0x10 in this field.

If an error occurs while the Excel platform is processing the message, the Excel platform returns a negative acknowledgment (NACK) value that indicates the reason for the error. Negative acknowledgements identify problems such as call processing anomalies and configuration errors. A negative acknowledgment value can be anything other than 0x10, which is reserved for positive acknowledgements.

Data

The contents of the data bytes vary for every message and response. Please refer to individual messages for data definitions.

Checksum

The value of the Checksum field is the sum of the values of all header and data bytes, except for the Frame field. The system calculates the checksum before it uses an escape sequence, if an escape sequence is required.

Message Format Documentation Conventions

This section describes the conventions used in this publication for the following:

• Byte Numbering

• Variable Number of Fields

• Word-sized Fields

• Bit Masks

• Double-Line in Table

Byte Numbering

In this Reference, the actual number of bytes in a message field is shown only if the value never changes. For example, the number of bytes in the header field is shown because the header bytes will always be 0-.

Variable Number of Fields

The number of bytes in a series often changes (for example, with variable data) so it cannot be shown in this Reference. In these cases, the first field is defined in the Reference, but subsequent fields are represented by vertical dots, as shown in below.

Word-size Fields

API messages frequently use multiple byte fields for the following:

• Timers

• Conference IDs

• PPL Event IDs

• PPL Component IDs

Fields that are more than one byte long use the Big Endian format of Most Significant Byte (MSB) first, Least Significant Byte (LSB) last.

For example, as shown in below, Byte 8 is the MSB and Byte 9 is the LSB for the Conference ID field.

If the Conference ID is 05, you would enter the ID as shown in the next figure. Note that the first value (MSB) is 0x00 until the value of the LSB field "overflows" (is greater than 255). These two-byte fields are often represented as a combined Hexadecimal number. For example, in the figure below, the combined representation of 0x00 and 0x05 would be 0x0005.

Figure 1-2 Conference ID

Bit Mask

A bit mask is a byte that uses its individual bits to enable or disable functions. Setting the bit enables the function. This process is shown in the following example, taken from the Alarm message:

Example:

Data[1] Span Status

This is a bit mask indicating the information that is sent and received on the span. You can set multiple bits.

Bit

0 Receiving Red

1 Receiving Remote Alarm Indication/Yellow

2 Receiving Loss of Signal

3 Receiving Out of Frame

4 Sending Red (AIS)

5 Sending Remote Alarm Indication/Yellow

6 Receiving AIS

7 Receiving constant E-bit with Remote Alarm Indication. This bit is
valid for E1 with insert CRC and Euro-ISDN.

When you print a message trace, you read a two-byte bit mask from right to left, as shown below (0 to 15).

Double Line in Table

A double line in a table indicates that you do not repeat the fields above it. In the example below, the double line between String 1 and String 2 indicates that you can have multiple strings in the ICB but that you do not repeat the information above the field, "String 2: BCD Digit Count."

Escape Sequences

The Excel platform uses the value 0xFE in the Frame field to indicate the beginning of a new frame. If a field value within a message or response is 0xFE, the Excel platform erroneously tries to process the next piece of data as a new message or response.

An escape sequence resolves this issue. Use the value 0xFD plus an extra byte that immediately follows it to send the values 0xFE or 0xFD. The table below shows the values that the system recognizes.

When the Excel platform reads the value 0xFD within a frame, it uses the following byte to one-complement the 0xFD value. The sum of the complement byte and 0xFD produces the actual value sent.

Important! You cannot use the values 0xFE or 0xFD immediately following the initial 0xFD value.

When you calculate the length of a message that uses an escape sequence, do not include the extra byte that you added to the message. The length of a message is defined before the escape sequence is used.

For example, if you are sending the Version Request message and it includes the value 0xFE:

The value of the Length field is the number of bytes between the Length and Checksum fields. The original length of this message is 0x. When you use the escape sequence, you add another byte to the message.

Although you added another byte to the message, you do not change the value of the Length field.

Basic Message Set

The primary function of the basic message set is to download the Excel platform Software from the host, and to query the Excel platform. When the Excel platform Software is completely downloaded, the Excel platform stops running from the Matrix Controller Series 3 card firmware, and starts running from the Matrix Controller RAM load. You can think of the Basic Message Set as a core group of messages.

The following messages comprise the basic message set:

• Alarm

• Alarm Cleared

• Become Active

• Card Status Query

• Clear System Software

• Download Begin BRecord

• Download Begin SRecord

• Download BRecord

• Download Complete

• Download SRecord

• Fault Log Query

• Poll

• Poll Interval Configure

• Poll Request

• Reset Matrix

• TFTP Control/Query

• Version Request