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 NMS ISDN Software

1.3.1 NMS ISDN Product Configurations

1.3.2 NMS ISDN Channelized Configuration

1.4 NMS ISDN Software Components

1.4.1 readme File

1.4.2 NMS ISDN Function Libraries

1.4.3 Header Files

1.4.4 ISDN Protocol Stack Downloadable Object Modules

1.4.5 System Configuration Files For Natural Access 4.0 18

For Natural Access Versions Prior to 4.0 18

1.4.6 Demonstration Programs

1.4.7 Trunk Control Program (TCP)

1.4.8 Parameter Files NMS ISDN Parameter Files (NCC Service) 20

NMS ISDN Parameter Files (ADI Service) 21

1.5 Other Components

1.5.1 Natural Access

1.5.2 Call Control Services under Natural Access

1.6 Developing an NMS ISDN Application

1.1 Introduction

This manual explains how to develop an ISDN-based telephony application using Natural MicroSystems ISDN software. This manual concentrates on building NMS ISDN applications that perform call control using a standard Natural Access call control API (NCC or ADI). For information on building applications that interface with the NMS ISDN protocol stack at lower layers, see the NMS ISDN Messaging API Developer's Reference Manual.

This document is targeted to developers of telephony and voice applications who are using Natural Access. This document defines telephony terms where applicable, but assumes that the reader is familiar with basic telephony concepts. It also assumes that the user is familiar with the C programming language.

1.2 Integrated Services Digital Network (ISDN)

This chapter:

• Discusses NMS ISDN software, and its role in an application.

• Lists and describes the NMS ISDN software components.

• Lists and describes the other hardware and software components required in an application.

• Outlines the application development process.

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 B.

1.3 NMS ISDN Software

NMS ISDN protocol software allows you to write Natural Access applications that communicate with T1 or E1 trunks to perform voice processing functions and call control using ISDN Common Channel Signaling protocols.

NMS ISDN software is designed to use one or more digital trunk interface boards (such as the AG Quad, AG 4000, or CG 6000 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 NMS ISDN Product Configurations

Using NMS ISDN software, you can access ISDN services in three ways:

• Configure the NMS ISDN software so an application can perform call control and other operations, using a standard Natural Access call control API (ADI or NCC).
  This NMS ISDN configuration is called the Channelized configuration. This is the interface described in this manual.

• Access ISDN services at the ACU SAPI. Using the NMS ISDN Messaging API, an application can then perform a wide range of Q.931 ISDN D channel functions.
  This NMS ISDN configuration is called the ACU configuration. For more information about this configuration, see the NMS ISDN Messaging API Developer's Reference Manual.

• Access ISDN services at the data link layer (Layer 2). Using the NMS 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 NMS ISDN configuration is called the LAPD configuration. For more information about this configuration, see the NMS 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 NMS ISDN Channelized Configuration

NMS ISDN allows you to access ISDN call control services using a standard Natural Access call control API (ADI or NCC). The NMS ISDN product provides access via standard API function calls - the same function calls used with any other trunk protocols (such as CAS). The NMS 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 board, one for each D channel. In the NMS 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 Natural Access application and a B channel on a trunk. At initialization, the application creates a context/TCP instance pair for each B channel (voice channel). The application communicates with the TCP via the 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 Natural 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 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.

  
  Note:	 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 NMS ISDN library. No other functions from this library are used in this configuration. A daemon program included with the NMS 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 board's CT Bus switch. The switch has certain default behavior, described in Section 3.3. Alternatively, the switch can be controlled using the Natural Access Switching service.

Figure 4. NMS ISDN Application Architecture (Channelized Configuration)

1.4 NMS ISDN Software Components

ISDN is implemented differently around the world. For this reason, NMS provides several variants of its NMS ISDN software for different countries or regions. The package for a variant contains the software modules you need to allow an board to communicate on a T1 or E1 trunk in the countries which use that variant.

The ISDN software package for a given variant contains the following:

• A readme file.

• NMS ISDN function libraries for Natural Access.

• Header files.

• Downloadable object modules containing the NMS ISDN protocol stack software.

• Sample 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 NMS 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 NMS ISDN software components are located after installation.

1.4.2 NMS 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 board, and to communicate with NCC and ADI services.

The following table lists Natural Access library names for Windows NT and UNIX:

Operating System	Libraries
Windows NT	isdnapi.lib, isdnapi.dll, nccisdn.lib, nccisdn.dll
UNIX	libnccisdn.so, libisdnapi.so

1.4.3 Header Files

The following header files supplied with NMS 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 and ISDN API function prototypes.
isdnparm.h	Parameter structure definitions and manifest constants for parameter structure fields.
isdntype.h	NMS type definitions, basic and derived types, and 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

The downloadable object module files contain the basic low-level software which a board requires to support ISDN. The modules are transferred from the host into on-board memory when the board boots.

Different module files are supplied for different configurations. The file you use depends upon what board type you are using. For more information about downloadable object modules, see the NMS ISDN Installation Manual.

1.4.5 System Configuration Files

When you set up your system, you specify configuration information for all boards in the system in a configuration file. System configuration files contain information which determines how to set up your boards for use. This information includes: whether a board performs switching, which board is the clock master, and which software modules to transfer to the board's memory on startup (including which TCPs to load).These files also contain country-specific information, and define 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. To learn how to modify your configuration file to set up your NMS ISDN software, see the NMS ISDN Installation Manual.

For Natural Access 4.0

To configure your boards based on the information in the configuration file, run the oamsys utility. This utility transfers to each board all software modules specified in the file, and performs any other configuration activities needed.

Use oamcfg to change to a board's configuration while the system is running. Modify the configuration file to make those changes effective when the system restarts.

NMS OAM is installed with Natural Access 4.0. For more information about NMS OAM, see the NMS OAM System User's Manual.

For Natural Access Versions Prior to 4.0

To configure your boards based on the information in the configuration file, run the agmon utility. This utility transfers to each board all software modules specified in the file, and performs any other configuration activities needed.

Edit the configuration file and then restart agmon to make your changes effective.

agmon is installed with Natural Access. For more information about agmon, see 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 TCP is included, named isd0.tcp. This TCP is used with the NMS ISDN software in Channelized configuration.

The TCP is transferred to on-board memory when the board is started. An instance of the TCP is associated with each context. A TCP mediates transactions between Natural Access, DSP resources, and the ISDN protocol stack.

1.4.8 Parameter Files

Parameter files are supplied with NMS ISDN software. They contain parameters and values that configure the NMS ISDN TCP. Some of these parameters are country-specific; that is, different values are supplied for them depending upon the target country.

Note: These files are useful only if you are configuring the NMS ISDN software for Channelized configuration (as documented in this manual).

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 detailed information about parameters, and how to load and change them, see Appendix A.

NMS 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 NMS ISDN parameters and default values. Changing these parameters directly affects all control messages (for example, 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.

NMS 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.

1.5 Other Components

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

• One or more T1 or E1 trunk interface boards.

• Natural Access version 3.0 or later.

  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 Natural Access

Natural 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. Natural Access service provide functions for telephony-related tasks such as call control, tone and DTMF tone generation and detection, and voice playing and recording.

Natural Access includes a service which controls switching. 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 Natural Access, see the Natural Access documentation.

1.5.2 Call Control Services under Natural Access

Under Natural 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 capabilities, and the ability to query a protocol's capabilities. If you are creating a new NMS 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 Natural Access 3.0, the call control functions within ADI are deprecated. Eventually, the ADI call control API will be phased out entirely.
  
  

1.6 Developing an NMS ISDN Application

To create an NMS ISDN application:

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