9.5.  Developing ADSI Applications

• 9.5.1.  One-Way ADSI Data Transfer
• Using dx_TxIottData( ) to Implement One-Way ADSI
• 9.5.2.  Two-Way ADSI Data Transfer
• Using dx_TxIottData( ) to Implement Two-Way ADSI
• Using dx_TxRxIottData( ) for Two-Way ADSI Transmissions
• 9.5.3.  Modifying Older One-Way ADSI Applications

This section provides the following information:

• A technical overview of how the one-way and two-way ADSI data transfer processes work
• Guidelines for using the Dialogic library functions to develop applications for both one-way and two-way ADSI data transfer
• Instructions for modifying older one-way ADSI applications to replace the dx_play( ) function with the dx_TxIottData( ) function

NOTE:

For more information about ADSI and two-way FSK, refer to the following Bellcore documents:

• For information about interface requirements, see Bellcore Technical Reference GR-30-CORE, Voiceband Data Transmission Interface Generic Requirements.
• For information about message requirements (how the data should be displayed on the CPE), see Bellcore Technical Reference TR-NWT-001273, Generic Requirements for and SPCS to Customer Premises Equipment Data Interface for Analog Display Services.
• For information about two-way FSK transmission, see the Bellcore Special Report SR-3462, A Two-Way Frequency Shift Keying Communication for the ADSI.

Bellcore documents can be obtained from Bellcore by calling 1-800-521-CORE.

9.5.1.  One-Way ADSI Data Transfer

In one-way ADSI data transfer, the ADSI server sends ADSI messages to a CPE device, such as an ADSI-compliant telephone. The transactions that occur between the server and the CPE during one-way ADSI data transfer are as follows:

1. The server initiates the data transfer by sending a CPE Alerting Signal (CAS) to the CPE.
2. When the CPE receives the CAS, the device generates an ACK (DTMF 'A' signal) to the server. At this point the CPE device has switched from voice mode to data mode. (If the CPE device remains in data mode, subsequent transmissions do not require the CAS.)

   NOTE:

   Only ADSI-compliant CPE devices will respond to the CAS sent by the server. Check with your manufacturer to verify that your CPE device is a true ADSI-compliant device. ADSI-compliant devices are also referred to as "Type 3 CPE Devices" by Bellcore and the EIA/TIA.

1. Upon receipt of the ACK signal, the server initiates the FSK transmission sequence. Each FSK transmission sequence can contain anywhere from 1 to 5 messages.
2. The CPE receives the FSK data and uses the checksum included within the sequence to determine the number of messages successfully received.
3. The CPE device then responds to the server with an acknowledgment digit (DTMF 'D') followed by a DTMF of '0' through '5,' which indicates the number of messages successfully received.
4. The server interprets the DTMF as follows:
   • ACK = 'D' followed by a DTMF in the range of 1 -- 5
   • NAK = 'D' followed by a DTMF '0'

Using dx_TxIottData( ) to Implement One-Way ADSI

The dx_TxIottData( ) function is used to send the CAS to the CPE and implement one-way ADSI data transfer. To transfer ADSI FSK data, the function parameters and structures must be configured as follows:

• set the wType parameter DT_ADSI
• configure the DX_IOTT structure with the appropriate ADSI FSK data file(s). The application is responsible for constructing the messages and checksums for each transmission
• set the termination conditions with the DV_TPT structure
• set dwTxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_ALERT to generate the CAS

The following scenario illustrates the function calls that are required to generate an initial CAS to the CPE and begin one-way ADSI data transfer. The chart describes what is happening on the voice channel between the server and the CPE.

Step	Server	Voice Channel	CPE
1 2 3 4 5 6	dx_clrdigbuf( ) dx_TxIottData( ) with dwTxDataMode = ADSI_ALERT dx_getdig( ) - retrieve ACK digits	Digit buffer cleared CAS----------------> Data file(s)--------> Digits received	<---ACK (DTMF 'A') NAK (DTMF '0') or <---ACK (DTMF 'Dx' where x = 1 to 5)

1. Prior to executing dx_TxIottData( ), the digit buffer for the desired voice channel is cleared using the dx_clrdigbuf( ) function.
1. The dx_TxIottData( ) function is issued. To generate an initial CAS to the CPE device, dwTxDataMode within ADSI_XFERSTRUC must be set to ADSI_ALERT.
2. The CAS is received by the CPE and the CPE sends an acknowledgment digit (DTMF 'A') to the voice device.

   NOTE:

   If the DTMF acknowledgment digit is not received from the CPE device within 500 ms following the end of the CAS, the function will return a 0 but the termination mask returned by ATDX_TERMMSK( ) will be TM_MAXTIME to indicate an ADSI protocol error. (The function will return a -1 if a failure is due to a general transmission error.)

1. Upon receipt of the DTMF 'A' ACK, the voice device automatically transmits the data file referenced in the DX_IOTT structure.
2. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.)

   NOTE:

   Upon successful completion, the function terminates with a TM_EOD (end of data) termination mask returned by ATDX_TERMMSK( ).

1. After completion of dx_TxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence from the CPE device. Set the DV_TPT tp_termno parameter to DX_DIGTYPE to receive the DTMF string "adx," where "x" is the message count acknowledgment digit (1-5).

After the CAS is sent to the CPE, as described in the preceding scenario, the CPE is in data mode. Provided that the ADSI messages sent to the CPE instruct the CPE to remain in data mode, subsequent ADSI transmissions to the CPE do not require the CAS. To send ADSI data without the CAS, set the dwTxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_NOALERT. All other settings are the same as above.

The following scenario illustrates the function calls that are required to transfer ADSI data when the CPE is already in data mode (without sending a CAS). The chart describes what is happening on the voice channel between the server and the CPE.

Step	Server	Voice Channel	CPE
1 2 3 4	dx_clrdigbuf( ) dx_TxIottData( ) with dwTxDataMode = ADSI_NOALERT dx_getdig( ) - retrieve ACK digits	Digit buffer cleared Data file(s)-----> Digits received	NAK (DTMF '0') or <--ACK (DTMF 'Dx' where x = 1 to 5)

1. Prior to executing dx_TxIottData( ), the dx_clrdigbuf( ) function is issued to ensure the voice channel digit buffer is empty.
1. The dx_TxIottData( ) function is issued with dwTxDataMode within the ADSI_XFERSTRUC set to ADSI_NOALERT. This initiates the immediate transfer of the data file(s) referenced in the DX_IOTT structure to the CPE device.
2. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.)
3. After completion of dx_TxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence from the CPE device. Set the DV_TPT tp_termno parameter to DX_DIGTYPE to receive the DTMF string "adx," where "x" is the message count acknowledgment digit (1-5).

9.5.2.  Two-Way ADSI Data Transfer

In two-way ADSI data transfer, both the ADSI server and CPE device can transmit and receive ADSI data messages. The CAS is used to initiate the transfer of ADSI FSK data and to return the CPE to voice mode after the data exchange is completed.

The transactions that occur between the server and the CPE in two-way ADSI data transfer are as follows:

1. The server initiates the data transfer by sending a CPE Alerting Signal (CAS) to the CPE equipment.
2. Upon receipt of the CAS, the CPE device generates an ACK (DTMF 'A' signal) to the server. At this point the CPE device has switched from voice mode to data mode. (Once the CPE device is in data mode, subsequent FSK data transmissions do not require the CAS.)

   NOTE:

   Only ADSI-compliant CPE devices will respond to the CAS sent by the server. Check with your manufacturer to verify that your CPE device is a true ADSI-compliant device. ADSI-compliant devices are also referred to as "Type 3 CPE Devices" by Bellcore.

1. When the ACK signal is received, the server initiates the FSK transmission sequence. Each FSK transmission sequence can contain anywhere from 1 to 5 messages. A "Switch to Peripheral Mode" message (using 0x0A as a 'requested peripheral' code) must be included within the FSK transmission sequence.
2. The CPE receives the FSK data and uses the checksum included within the sequence to determine the number of messages successfully received.
3. The CPE device then responds to the server with a DTMF 'D' followed by a DTMF '0' through '5' to indicate the number of messages successfully received. In addition, the CPE device acknowledges the "Switch to Peripheral Mode" message by responding with either
   • DTMF 'B,' indicating that the requested peripheral is available and on line
   • DTMF 'A,' indicating that the requested peripheral is not available
4. The server interprets the DTMF signals as follows:
   • 'D' followed by a DTMF in the range of 1 -- 5 = ACK
   • 'D' followed by a DTMF '0' = NAK
   • DTMF 'B' = requested peripheral available (ready to receive and transmit ADSI data)
   • DTMF 'A' = requested peripheral unavailable (unable to transmit or receive ADSI data)

Once the CPE device has acknowledged the "Switch to Peripheral Mode" message, the CPE may transmit data to the server at any time. The server must be prepared to receive data at any time until the CPE peripheral is switched back to voice mode. To return the CPE peripheral to voice mode, the server sends a CAS to the CPE. Upon receipt of the CAS, the CPE responds with a DTMF 'A' signal. Receipt of DTMF 'A' at the server completes the return to voice mode transition.

Using dx_TxIottData( ) to Implement Two-Way ADSI

The dx_TxIottData( ) function is used to implement two-way ADSI data transfer. The dx_TxIottData( ) function transmits the CAS and the subsequent "Switch to Peripheral Mode Message" to the CPE. To transfer ADSI FSK data, set the parameters and configure the structures as described below:

• set the wType parameter DT_ADSI
• configure the DX_IOTT structure with the appropriate ADSI FSK data file(s), including the "Switch to Peripheral Mode" message. The application is responsible for constructing the messages and checksums for each transmission
• set the termination conditions with the DV_TPT structure
• set dwTxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_ALERT to generate the CAS

The following scenario illustrates the function calls that are required to generate an initial CAS to the CPE and begin two-way ADSI data transfer. The chart describes what is happening on the voice channel between the server and the CPE.

Step	Server	Voice Channel	CPE
1 2 3 4 5 6 7	dx_clrdigbuf( ) dx_TxIottData( ) with dwTxDataMode = ADSI_ALERT dx_getdig( ) - retrieve ACK digits	Digit buffer cleared CAS----------------> Data file(s) including 'Switch to Peripheral Mode' --------> Digits received Digits received	<---ACK (DTMF 'A') NAK (DTMF '0') or <---ACK (DTMF 'Dx' where x = 1 to 5) Peripheral available (DTMF 'B') or <---Peripheral unavailable (DTMF 'A')

1. Prior to executing dx_TxIottData( ) , the digit buffer for the desired voice channel is cleared using the dx_clrdigbuf( ) function.
1. The dx_TxIottData( ) function is issued. To generate an initial CAS to the CPE device, dwTxDataMode within ADSI_XFERSTRUC must be set to ADSI_ALERT.
2. The CAS is received by the CPE and the CPE sends an acknowledgment digit (DTMF 'A') to the voice device.

   NOTE:

   If the DTMF acknowledgment digit is not received from the CPE device within 500 ms following the end of the CAS, the function will return a 0 but the termination mask returned by ATDX_TERMMSK( ) will be TM_MAXTIME to indicate an ADSI protocol error. (The function will return a -1 if a failure is due to a general transmission error.)

1. Upon receipt of the DTMF 'A' ACK, the voice device automatically transmits the data file referenced in the DX_IOTT structure, which must include the "Switch to Peripheral Mode" message.
2. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.)

   NOTE:

   Upon successful completion, the function terminates with a TM_EOD (end of data) termination mask returned by ATDX_TERMMSK( ).

1. The CPE responds to the "Switch to Peripheral Mode" message with either DTMF 'B' if the peripheral is available or DTMF 'A' if the peripheral is unavailable.
2. After completion of dx_TxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence from the CPE device. Set the DV_TPT tp_termno parameter to DX_DIGTYPE to receive the DTMF string "adxb," where "x" is the message count acknowledgment digit (1-5). When the DTMF string is received, additional messages can be sent and received between the server and the CPE peripheral.

Using dx_TxRxIottData( ) for Two-Way ADSI Transmissions

After the two-way ADSI transmission is implemented using the dx_TxIottData( ) function, additional ADSI FSK messages are typically sent to the CPE peripheral to configure the display and soft keys. Since at this point the CPE peripheral has been configured to send data to the server, the dx_TxRxIottData( ) function should be used to send the data to the CPE and then quickly turnaround and be ready to receive data from the CPE.

To transfer ADSI FSK data using dx_TxRxIottData( ), set the function parameters and configure the structures as described below:

• set wType to DT_ADSI
• configure DX_IOTT structures referenced by lpTxIott and lpRxIott with the appropriate ADSI FSK data files. The application is responsible for constructing the messages and checksums for each transmission
• set the termination conditions for the transmit and receive portions of the function with the DV_TPT structures referenced by lpTxTerminations and lpRxTerminations, respectively
• set dwTxDataMode and dwRxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_NOALERT to transmit and receive FSK ADSI data without generation of a CAS

The following scenario illustrates the function calls that are required to send and receive FSK ADSI data between the server and the CPE. The chart describes what is happening on the voice channel between the server and the CPE.

Step	Server	Voice Channel	CPE
1 2 3 4 5 6 7 8	dx_clrdigbuf( ) dx_TxRxIottData( ) with dwTxDataMode and dwRxDataMode = ADSI_NOALERT dx_getdig( ) - retrieve ACK digits Thread to process received data dx_Rx_IottData( ) with dwRxDataMode = ADSI_NOALERT for next data burst from CPE	Digit buffer cleared Data file(s) ------> Digits received Wait for data Data received Wait for data	NAK (DTMF '0') or <---ACK (DTMF 'Dx' where x = 1 to 5) <---Send FSK ADSI data to server

1. Prior to executing dx_TxIottData( ), the digit buffer for the desired voice channel is cleared using the dx_clrdigbuf( ) function.
1. The dx_TxRxIottData( ) function is issued with dwTxDataMode and dwRxDataMode within ADSI_XFERSTRUC set to ADSI_NOALERT. This initiates the transmission of the data file referenced in the DX_IOTT structure to the CPE. The server voice channel is placed automatically in FSK ADSI data receive mode to receive data from the CPE.
2. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.)
3. The server voice channel is ready and waiting for data from the CPE.
4. The CPE sends FSK ADSI data to the server. When an ADSI FSK message is successfully received or when the termination conditions set in lpRxTerminations are met, the dx_TxRxIottData( ) function completes.
5. After completion of dx_TxRxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence for the transmit portion of the function. When the DTMF string is received, additional messages can be sent and received between the server and the CPE peripheral.
6. In another thread of execution at the server, the received message(s) are processed by the application to determine the number of messages received and the integrity of the information.
7. The dx_RxIottData( ) function is issued to receive messages from the CPE. This function should be issued as soon as possible because the CPE peripheral can send data to the server after a minimum of 100 msec following the completion of its transmission.

 
If data needs to be transmitted to the CPE when the server is waiting to receive data, issue dx_stopch( ) to terminate the current dx_RxIottData( ) function. Upon confirmation of termination of dx_RxIottData( ), issue dx_clrdigbuf( ) to clear the voice device channel buffer, and then issue dx_TxIottData( ) to send the data to the CPE.


9.5.3.  Modifying Older One-Way ADSI Applications

Prior to the release of the two-way ADSI, including two-way FSK,, applications used the dx_play( ) function to implement one-way ADSI applications. With two-wayADSI, transmit and receive data functions are introduced for data transfer. To take advantage of on-hook ADSI transfer in a one-way ADSI application, and/or to introduce two-way FSK concepts into applications, older applications need to be modified.

Applications developed prior to the release of the two-wayADSI use the following sequence of commands to generate a CAS tone followed by transmission of an ADSI file:

   /* Setup DX_IOTT to play from disk */  
   /* Setup DV_TPT for termination conditions */  
   /* Initiate ADSI play when DTMF 'A' is received from CPE */  
   parmval = DM_A;  
   if (dx_setparm(Voice_Device, DXCH_DTINITSET, (void *)&parmval) == -1) {  
      /* Process error */     
   }  
   /* Clear digit buffer for impending ADSI protocol DTMFs */  
   if (dx_clrdigbuf(Voice_Device) == -1) {  
      /* Process error */  
   }  
     /* Send CAS followed by ADSI data when DTMF 'A' is received */  
   if (dx_play(Voice_Device, &Iott_struct, &Tpt_struct, EV_SYNC | PM_ADSIALERT) == -1) {  
      /* Process error */  
   }

In older applications, the use of dx_play( ) for ADSI transmission can be replaced with the specialized dx_TxIottData( ) data transfer function. The same DV_TPT and DX_IOTT are used by dx_TxIottData( ) as for dx_play( ), however, the following additional parameters need to be configured:

• wType - specifies the data type transferred. To transfer ADSI FSK data, wType is set to DT_ADSI.
• lpParams - specifies the data type specific information. To transmit CAS followed by the ADSI FSK message, dwTxDataMode within the ADSI_XFERSTRUC data structure pointed to by lpParams is set to ADSI_ALERT.

Using these parameters, the CAS will be transmitted and, upon receipt of DTMF 'A,' the ADSI FSK data will be sent to the CPE device.

The following sample code illustrates the use of the dx_TxIottData( ) function to generate a CAS tone and transmit an ADSI file:

   /* Setup DX_IOTT to play from disk */  
   /* Setup DV_TPT for termination conditions */  
   /* Setup ADSI_XFERSTRUC to send CAS followed by ADSI FSK upon receipt of DTMF 'A' */  
   adsimode.cbSize = sizeof(adsimode);  
   adsimode.dwTxDataMode = ADSI_ALERT;  
   /* Clear digit buffer for impending ADSI protocol DTMFs */  
   if (dx_clrdigbuf(Voice_Device) == -1) {  
      /* Process error */  
   }  
   /* Send CAS followed by ADSI data when DTMF 'A' is received */  
   if (dx_TxIottData(Voice_Device, &IOTT, &TPT, DT_ADSI, &adsimode, EV_SYNC) == -1) {  
      /* Process error */  
   }

Click here to contact Dialogic Customer Engineering