(Page 1 of 1 in this chapter) Version

Chapter 1

Introduction

1.1 Introduction

1.2 Integrated Services Digital Network (ISDN)

: 1.2.1 ISDN Protocols and Protocol Layering
: 1.2.2 ISDN Carriers

1.3 AG ISDN Software

: 1.3.1 AG ISDN Product Configurations
: 1.3.2 AG ISDN Channelized Configuration

1.4 AG ISDN Software Components

: 1.4.1 readme File
: 1.4.2 AG ISDN Function Libraries
: 1.4.3 Header Files
: 1.4.4 ISDN Protocol Stack Downloadable Object Modules
: 1.4.5 AG Configuration Files
: 1.4.6 Demonstration Programs
: 1.4.7 Trunk Control Program (TCP)
: 1.4.8 Parameter Files

1.5 Other Components

: 1.5.1 CT Access
: 1.5.2 Call Control Services under CT Access
: 1.5.3 agmon and the AG Configuration File

1.6 Developing an AG ISDN Application

1.1 Introduction

AG ISDN allows you to create powerful applications that interact with ISDN services in a variety of ways, using the NMS CT Access application programming interfaces (APIs) and one or more AG boards.
This chapter: Discusses AG ISDN software, and its role in an application. Lists and describes the AG ISDN software components. Lists and describes the other hardware and software components required in an application. Outlines the application development process.

1.2 Integrated Services Digital Network (ISDN)

Integrated Services Digital Network (ISDN) is a continually evolving international standard for networking a wide range of services, including voice and non-voice services. The network is completely digital, from one end to the other: voice information is digitized and sent in digital form. Signaling information is sent separately from voice information, using a method called common channel signaling (CCS).

1.2.1 ISDN Protocols and Protocol Layering

ISDN communications can be described at many levels, from the way bits are transferred from machine to machine to the sets of messages computers pass to one another. A scheme for communication at a certain level is called a protocol.
In the late 1970's, the International Standards Organization (ISO) established the Open Systems Interconnect (OSI) model for communication. ISDN is based on this model. In OSI, seven separate levels, or layers, of communication are defined. The first three layers, called the chained layers, are the lowest levels. The chained layers are: The physical layer (layer 1). This is the electrical and mechanical layer. Protocols for this layer describe, from an electrical and mechanical perspective, the methods used to transfer bits from one device to another. One protocol used at this layer is CCITT recommendation I.430/I.431. The data link layer (layer 2). This is the layer above the physical layer. Protocols for this layer describe methods for error-free communication between devices across the physical link. One protocol used at this layer is CCITT recommendation Q.921, also known as Link Access Procedures on the D Channel (LAPD). The network layer (layer 3). This is the layer above the data link layer. Protocols for this layer describe methods for transferring information between computers. They also describe how data is routed within and between networks. One protocol used at this layer is CCITT recommendation Q.931.
Layers higher than these are end-to-end layers. They describe how information is exchanged and delivered end-to-end. They also define process-to-process communication, and describe application-independent user services, user interfaces and applications, etc. Figure 1. OSI Protocol Layering Model
The functionality provided by a layer includes the services and functions of all of the layers below it. A Service Access Point (SAP) is the point at which a layer provides services to the layer directly above it. With each SAP is associated a unique Service Access Point Identifier (SAPI).

1.2.2 ISDN Carriers

ISDN is transmitted over standard T1 and E1 carriers. These are typically four-wire digital transmission links. T1 is used mainly in the United States, Canada, Hong Kong, Taiwan, and Japan. E1 is used throughout most of the rest of the world.
Data on a T1 or E1 trunk is transmitted in channels. Each channel carries information digitized at 64000 bits per second (bps). For primary rate ISDN, T1 carries 24 channels. E1 carries 32 channels.
With primary-rate ISDN, the channels are usually used as follows: On a T1 trunk, 23 of the 24 channels carry data: voice, audio, data and/or video signals. These channels are called bearer channels (B channels). On an E1 trunk, 30 of the 32 channels are bearer channels. On a T1 or E1 trunk, one channel carries signaling information for all B channels. This is called the D channel. Figure 2. T1 Trunk (Standard Configuration)
In setups with multiple T1 ISDN trunks, a Non-Facility Associated Signaling (NFAS) configuration is often used. In this configuration, the D channel on one of the ISDN trunks carries signaling for all channels on several other trunks. This leaves channel 24 free on each of the other trunks to be used as another B channel. (See Figure 3.) Figure 3. Sample NFAS Configuration
NFAS configurations are not supported on E1 trunks. For more information about NFAS, see Appendix C.

1.3 AG ISDN Software

Alliance Generation (AG) ISDN protocol software allows you to write CT Access applications that communicate with T1 or E1 trunks to perform voice processing functions and call control using ISDN Common Channel Signaling protocols.
AG ISDN software is designed to use one or more AG digital boards (such as the AG Quad, AG 4000, AG-T1, or AG-E1 boards) as the physical interface to trunk lines. In addition to line interfaces, these boards also feature powerful on-board digital signal processing (DSP) resources that can handle much of the call control and voice processing overhead.

1.3.1 AG ISDN Product Configurations

Using AG ISDN software, you can access ISDN services in three ways: Configure the AG ISDN software so an application can perform call control and other operations, using the standard CT Access Natural Call Control API. This AG ISDN configuration is called the Channelized configuration. This is the interface described in this manual. Access ISDN services at the ACU SAPI. Using the AG ISDN Messaging API, an application can then perform a wide range of Q.931 ISDN D channel functions. This AG ISDN configuration is called the ACU configuration. For more information about this configuration, see the AG ISDN Messaging API Developer's Reference Manual. Access ISDN services at the data link layer (Layer 2). Using the AG ISDN Messaging API, an application can then send and receive I-frame data in LAPD messages. This data typically consists of Q.931 messages. This AG ISDN configuration is called the LAPD configuration. For more information about this configuration, see the AG ISDN Messaging API Developer's Reference Manual.
You specify the configuration to use when initializing the ISDN protocol stack, as described in Chapter 3.

1.3.2 AG ISDN Channelized Configuration

AG ISDN allows you to access ISDN call control services using the standard CT Access Natural Call Control API. The AG ISDN product provides access via standard API function calls - the same function calls used with any other trunk protocol (such as CAS or loop start). The AG ISDN Natural Call Control interface is described in this manual.
In Channelized configuration (see Figure 4) the following components run on the board: The ISDN protocol stack. One or more instances of this stack run on the AG board, one for each D channel. In the AG ISDN Channelized configuration, the protocol stack runs in Channelized stack mode. In this mode, the stack implements all ISDN layer 2 and layer 3 functionality. When signaling messages for a particular B channel arrive on the D channel, an entity within the stack, the channelizer, routes them to the TCP associated with that channel (see below). A TCP (trunk control program). A TCP serves as the call control interface between the CT Access application and a B channel on a trunk. At initialization, the application creates a CTA context/TCP instance pair for each B channel (voice channel). The application communicates with the TCP via the CTA context. The TCP for a B channel serves as the interface between the application and the ISDN protocol stack for all signaling for that B channel. It translates CT Access commands involving signaling for the B channel into ISDN messages, and sends them to the ISDN protocol stack, which controls the D channel. It interprets signaling messages coming from the ISDN protocol stack, translates them into appropriate events and sends them to the application via the CTA context. During call setup, the TCP has exclusive use of the DSP resources allocated to the B channel. Once the call is in the connected state, the application also has direct control of the DSP resources for the channel. DSP resources are temporarily available to the application during call setup if the application elects to play user audio while accepting or rejecting a call.
In Channelized configuration, ISDN protocol stack instances are started and stopped using two functions from the AG ISDN library. No other functions from this library are used in this configuration. A daemon program included with the AG ISDN software can start the stack before ISDN applications are launched, and stop the stack after they are shut down. Chapter 7 documents this daemon program.
B channel information is routed to the DSP resources through the AG board's MVIP switch. The switch has certain default behavior, described in Section 3.3. Alternatively, the switch can be controlled using the CT Access Switching service. Figure 4. AG ISDN Application Architecture (Channelized Configuration)

1.4 AG ISDN Software Components

ISDN is implemented differently around the world. For this reason, NMS provides several variants of its AG ISDN software for different countries or regions. The package for a variant contains the software modules you need to allow an AG board to communicate on a T1 or E1 trunk in one or more of the countries which use that variant.
The ISDN software package for a given variant contains the following: A readme file. AG ISDN function libraries for CT Access. Header files. Downloadable object modules containing the AG ISDN protocol stack software. Sample AG configuration files. Demonstration programs, with their source code files and makefiles. A Trunk Control Program (TCP). Several parameter files, in binary format (.pf files) and in ASCII format (.par files). These files contain AG ISDN parameters. Certain parameters in these files are set to values specific to a certain country or variant.
The sections that follow briefly describe each of these components.

1.4.1 readme File

This ASCII text file contains release information that does not appear in other documentation. The file is named readme_isdn.txt. Consult this file to learn where the AG ISDN software components are located after installation.

1.4.2 AG ISDN Function Libraries

These components run on the host computer. They are used by the application program to interact with the ISDN protocol stacks running on the AG board, and to communicate with NCC and ADI services.
CT Access library names are listed for Windows NT and UNIX: Windows NT UNIX isdnapi.lib, isdnapi.dll libisdnapi.so nccisdn.lib, nccisdn.dll libnccisdn.so

Windows NT	UNIX
`isdnapi.lib, isdnapi.dll`	`libisdnapi.so`
`nccisdn.lib, nccisdn.dll`	`libnccisdn.so`

1.4.3 Header Files

The following header files supplied with AG ISDN software are used in Channelized configuration: Filename Description isdnval.h Defines for Q.931 messages created by the stack. isdndef.h Event code definitions. ISDN API function prototypes. isdnparm.h Parameter structure definitions. Manifest constants for parameter structure fields. isdntype.h NMS type definitions, basic and derived types, entity identifiers. nccxadi.h NCC parameter structures. nccadi.h NCC values for mediamask, connectmask and disconnectmask. nccxisdn.h ISDN parameter structures and values for the NCC service. adiisd.h ISDN parameter structures and values for the ADI service.

Filename	Description
`isdnval.h`	Defines for Q.931 messages created by the stack.
`isdndef.h`	Event code definitions. ISDN API function prototypes.
`isdnparm.h`	Parameter structure definitions. Manifest constants for parameter structure fields.
`isdntype.h`	NMS type definitions, basic and derived types, entity identifiers.
`nccxadi.h`	NCC parameter structures.
`nccadi.h`	NCC values for mediamask, connectmask and disconnectmask.
`nccxisdn.h`	ISDN parameter structures and values for the NCC service.
`adiisd.h`	ISDN parameter structures and values for the ADI service.

1.4.4 ISDN Protocol Stack Downloadable Object Modules

A downloadable object module file contains the basic low-level software which an AG board requires to support ISDN. The module is transferred from the host into on-board memory using the agmon utility when the AG board boots.
Different module files are supplied for different configurations. The file you use depends upon what AG board type you are using. For more information about the downloadable object modules, see the AG ISDN Installation Manual.

1.4.5 AG Configuration Files

An AG configuration file contains information which agmon reads to determine how to set up your boards for use. This file also contains country-specific information, and defines what trunks are assigned to which D-channels.
Several example files are included, describing ISDN configurations for different boards. You can use these files to create a file describing your hardware and software setup. For details, see the AG ISDN Installation Manual and the AG Runtime Configuration and Developer's Manual.

1.4.6 Demonstration Programs

Several demonstration programs are included, with their source code files and makefiles. For details, see Chapter 7.

1.4.7 Trunk Control Program (TCP)

One trunk control program (TCP) is included, named isd0.tcp. This TCP is used with the AG ISDN software in Channelized configuration.
The TCP is transferred to on-board memory by agmon. An instance of the TCP is associated with each CTA context. A TCP mediates transactions between CT Access, DSP resources, and the ISDN protocol stack.

1.4.8 Parameter Files

Parameter files are supplied with AG ISDN software. They contain parameters and values that configure the AG ISDN TCP. Some of these parameters are country-specific; that is, different values are supplied for them depending upon the target country. These files are useful only if you are configuring the AG ISDN software for Channelized configuration (as documented in this manual). For more information, see Section 3.6.2, Starting a TCP on a CTA Context.

WARNING:

Changing the values of country-specific parameters may affect the regulatory approvals in the target country.
The following are lists of parameter files supplied for each software package. The list of parameter files relevant to your application differs depending upon whether you are using the Natural Call Control (NCC) service for call control (recommended) or using the ADI service call control functions.
For more information about the parameters in these files, see Appendix B. AG ISDN Parameter Files (NCC Service)
The following is a list of parameter files relevant to your application if you are using the NCC service for call control: File Type/Name Description nccxadicty.pf nccstartcty.pf · cty is the three character code of the target country. For example, the code for Australia is aus. Thus the versions of these files for Australia are nccxadiaus.pf and nccstartaus.pf. Binary parameter files containing a set of country-specific values for NCC service parameters. Most of the values in these files should not be changed. Changing certain values may affect the regulatory approvals in the target country. nccxisdn.pf A binary parameter file containing a set of AG ISDN parameters and default values. Changing these parameters directly affects all control messages (e.g., messages associated with NCC primitives). To change them correctly, you must have knowledge of the ISDN specifications for the target country. nccxadicty.par nccstartcty.par nccxisdn.par ASCII versions of the above files.
AG ISDN Parameter Files (ADI Service)
The following is a list of parameter files relevant to your application if you are using the ADI service for call control: File Type/Name Description isdcty.pf · cty is the three character code of the target country. For example, the code for Australia is aus. Thus the version of this file for Australia is isdaus.pf. A binary parameter file containing the complete set of parameters and default values, including country-specific parameters which should not be changed. adiisd.pf A binary parameter file containing the parameters for the country which was chosen as the "default" during installation. adiisd.par An ASCII version of the above file.

WARNING:	Changing the values of country-specific parameters may affect the regulatory approvals in the target country.

File Type/Name	Description
`nccxadi`cty`.pf` `nccstart`cty`.pf` · cty is the three character code of the target country. For example, the code for Australia is `aus`. Thus the versions of these files for Australia are `nccxadiaus.pf` and `nccstartaus.pf`.	Binary parameter files containing a set of country-specific values for NCC service parameters. Most of the values in these files should not be changed. Changing certain values may affect the regulatory approvals in the target country.
`nccxisdn.pf`	A binary parameter file containing a set of AG ISDN parameters and default values. Changing these parameters directly affects all control messages (e.g., messages associated with NCC primitives). To change them correctly, you must have knowledge of the ISDN specifications for the target country.
`nccxadi`cty`.par` `nccstart`cty`.par` `nccxisdn.par`	ASCII versions of the above files.

File Type/Name	Description
`isd`cty`.pf` · cty is the three character code of the target country. For example, the code for Australia is `aus`. Thus the version of this file for Australia is `isdaus.pf`.	A binary parameter file containing the complete set of parameters and default values, including country-specific parameters which should not be changed.
`adiisd.pf`	A binary parameter file containing the parameters for the country which was chosen as the "default" during installation.
`adiisd.par`	An ASCII version of the above file.

1.5 Other Components

In addition to the AG ISDN software, you will need the following components to build an ISDN protocol application:

One or more Alliance Generation T1 or E1 trunk interface boards.

CT Access version 3.0 or later.

agmon - the AG board loading and monitoring program. This utility is supplied with AG boards and with CT Access.

WARNING:

Natural MicroSystems obtains board-level approvals certificates for supported countries. Some countries require that you obtain system-level approvals before connecting a system to the public network. To learn what approvals you require, contact the appropriate regulatory authority in the target country.

WARNING:	Natural MicroSystems obtains board-level approvals certificates for supported countries. Some countries require that you obtain system-level approvals before connecting a system to the public network. To learn what approvals you require, contact the appropriate regulatory authority in the target country.

1.5.1 CT Access

CT Access is a complete development environment for telephony applications. It provides a standard set of telephony functions grouped into logical services, each of which has a standard API. CT Access service provide functions for telephony-related tasks such as call control, tone and DTMF tone generation and detection, and voice playing and recording.
CT Access includes a service which controls switching on MVIP-compliant devices. You can use this service to make or break connections, send patterns, sample data, etc. Alternatively, you can use the swish standalone utility to control switching interactively or in a batch mode.
For general information about installing and using CT Access, see the CT Access documentation.

1.5.2 Call Control Services under CT Access

Under CT Access, there are two services available which an application can use to perform call control: The Natural Call Control (NCC) service. This service features a protocol- independent API, separate call and line state machines, call hold/retrieve, and the ability to query a protocol's capabilities. If you are creating a new AG ISDN application, use this service to perform your call control operations. The ADI service. This service includes basic call control functions. These functions have been superseded by the NCC service. If your application currently uses the ADI service for call control, consider migrating to the NCC service for better performance, new features, and more control over your application's call control functionality. For more information, see the Natural Call Control Service Developer's Reference Manual. Note: With the release of CT Access 3.0, the call control functions within ADI will be considered deprecated functions. Eventually, the ADI call control API will be phased out entirely.

1.5.3 agmon and the AG Configuration File

When you set up your system, you specify configuration information for all AG boards in the system in an AG configuration file. This information includes: whether a board performs MVIP switching, which board is the MVIP clock master, which software modules to transfer to the AG board's memory on startup (including which TCPs to load), and other settings. To learn how to modify your AG configuration file to set up your AG ISDN software, see the AG ISDN Installation Manual and the AG Runtime Configuration and Developer's Manual.
To configure your boards based on the information in the AG configuration file, run the agmon utility. agmon transfers to each board all software modules specified in the file, and performs any other configuration activities needed. Leave it running so that it can monitor the AG boards for errors and other events.
Whenever you make a change to your AG configuration file, restart agmon to make your changes effective.
agmon is installed with CT Access. For more information, see the AG Runtime Configuration and Developer's Manual.

1.6 Developing an AG ISDN Application

To create an AG ISDN application: Step Where Step is Documented 1. Install AG digital trunk interface boards in a system, and any other boards you will need in your application. The installation manuals for your AG boards 2. Install CT Access. CT Access Installation Manual or Natural Access installation booklet 3. Install the AG ISDN software for each target country where your application will be used. AG ISDN Installation Manual 4. Edit your AG configuration file so it describes all AG boards in your system. The AG ISDN Installation Manual, the installation manuals for your AG boards, and the AG Runtime Configuration and Developer's Manual 5. Test your hardware installation. The installation manuals for your AG boards 6. Write your application. This manual, the AG ISDN Messaging API Developer's Reference Manual, and the CT Access documentation set

Step	Where Step is Documented
1. Install AG digital trunk interface boards in a system, and any other boards you will need in your application.	The installation manuals for your AG boards
2. Install CT Access.	CT Access Installation Manual or Natural Access installation booklet
3. Install the AG ISDN software for each target country where your application will be used.	AG ISDN Installation Manual
4. Edit your AG configuration file so it describes all AG boards in your system.	The AG ISDN Installation Manual, the installation manuals for your AG boards, and the AG Runtime Configuration and Developer's Manual
5. Test your hardware installation.	The installation manuals for your AG boards
6. Write your application.	This manual, the AG ISDN Messaging API Developer's Reference Manual, and the CT Access documentation set

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com