3.1 Introduction

3.2 Adding AG Configurations to the NMS OAM Database

3.3 Configuring the System Using oamsys

3.3.1 Creating a System Configuration File for oamsys

Sample System Configuration File

3.3.2 Launching oamsys

3.4 Changing Configuration Parameter Settings

3.4.1 Board Keyword Files

3.4.2 Specifying Configuration File Location

3.5 Configuring Board Clocking

3.5.1 Clocking References

3.5.2 Clock Fallback

3.5.3 Clocking Capabilities

Clocking Capabilities as Primary Master

Clocking Capabilities as Secondary Master

Clocking Capabilities as Slave

Other Clocking Capabilities

3.5.4 Configuring CT Bus Clocks With Keywords

Configuring the Primary Clock Master

Configuring the Secondary Clock Master

Configuring Clock Slaves

Configuring Standalone Boards

3.5.5 Multiple Board System Example

3.6 Echo Cancellation

3.7 Sample Board Keyword File

3.7.1 AG 4000C Board Keyword File

3.1 Introduction

This chapter describes how to configure and start the board after the software is installed. It also provides configuration information to use when adding the boards into the NMS OAM database.

3.2 Adding AG Configurations to the NMS OAM Database

For NMS OAM to be able to configure and start the boards, each board must have a separate set of configuration parameters and values in the NMS OAM database. Each parameter and value is expressed as a keyword name/value pair (for example, AutoStart = NO). You can query the NMS OAM database for keyword values for any component. Keywords and values can be added, modified, or deleted.

To use NMS OAM or any related utility, ensure that the Natural Access Server (ctdaemon) is running. For more information about ctdaemon, refer to the Natural Access Developer's Reference Manual.

The following utilities are shipped with NMS OAM:

Utility	Description
oamsys	Performs system configuration and board startup. Configures the NMS OAM database based on system configuration files you supply and then attempts to start all boards listed in the database.
oamcfg	Provides greater access to individual OAM service configuration functions. For more information about this utility, refer to the NMS OAM System User's Manual.

Note: An application can control NMS OAM programmatically through the OAM service API. For more information, refer to the NMS OAM Service Developer's Reference Manual.

3.3 Configuring the System Using oamsys

To configure a system using the oamsys utility:

1. Install the boards and software as described in Chapter 2.

2. Determine the PCI bus and slot locations of the boards, using the pciscan utility. The pciscan utility identifies the NMS PCI boards installed in the system, and returns each board's bus, slot, interrupt, and board type.

3. Create a system configuration file describing the board configuration. In this file, give each board a unique name and board number.

4. Use oamsys to set up records in the NMS OAM database based on this file and to start all installed boards.
   Note: If you want to determine the location of a specific board, use blocate to associate the PCI bus assignment to a physical board by flashing an LED on the board. To flash the LED on a board, call blocate with the PCI bus and PCI slot locations.

For more information about pciscan and blocate, refer to the NMS OAM System User's Manual.

3.3.1 Creating a System Configuration File for oamsys

Create a system configuration file describing all of the boards in your system. oamsys creates the records, and then directs the OAM service to start the boards, configured as specified.

The system configuration file is typically named oamsys.cfg. By default, oamsys looks for a file with this name when it starts up.

Refer to the NMS OAM System User's Manual for specific information on the syntax and structure of this file.

The following chart describes the AG board-specific settings to include in the system configuration file for each AG board:

Keyword	Description	Allowed Values for AG Boards
[name]	Name of the board to be used to refer to the board in the software. The board name must be unique.	Any string, in square brackets [].
Product	Name of the board product.	· AG_4000C_4T1 · AG_4000C_4E1 · AG_4000C_2T1 · AG_4000C_2E1
Number	Board number you will use in your Natural Access application to refer to the board.	Each board's number must be unique.
Bus	PCI bus number. The bus:slot location for each board must be unique.	Values returned by pciscan.
Slot	PCI slot number. The bus:slot location for each board must be unique.	Values returned by pciscan.
File	Name of the board keyword file containing settings for the board. Several board keyword files are installed with the AG software, one for each country or region.	You can create your own custom board keyword file if you wish. For details, refer to Section 3.4, Changing Configuration Parameter Settings. You can specify more than one file after the File keyword: File=mya.cfg myb.cfg myc.cfg Alternatively, you can specify the File keyword more than once: File = mya.cfg File = myb.cfg File = myc.cfg Board keyword files are sent in the order listed. The value for a given keyword in each file overrides any value specified for the keyword in earlier files.

Sample System Configuration File

The following system configuration file describes two AG 4000C T1 boards, both to be configured for the United States:

[First AG 4000C]
Product = AG_4000C_4T1
Number  = 0
Bus     = 0
Slot    = 15
File    = agpi4000.cfg

[Second AG 4000C]
Product = AG_4000C_4T1
Number  = 1
Bus     = 0
Slot    = 16
File    = agpi4000.cfg

3.3.2 Launching oamsys

To launch oamsys, enter oamsys on the command line.

If you invoke oamsys without command line options, it searches for a file named oamsys.cfg in the paths specified in the AGLOAD environment variable.

When invoked with a valid filename, oamsys:

• Checks the syntax of the system configuration file and verifies that all required keywords are present.
  Note: oamsys checks the syntax only on the system configuration file, and not on any board keyword files referenced in the system configuration file. oamsys reports all syntax errors it finds.

• Checks for uniqueness of board name, number and bus/slot.

• Deletes all board configuration information currently stored in the NMS OAM database (if there is any).

• Sets up the NMS OAM database and creates all records as described in the system configuration file.

• Attempts to start all boards as described in the database.
  Note: ctdaemon must be running for oamsys to operate. For more information about the Natural Access Server (ctdaemon), refer to the Natural Access Developer's Reference Manual.

3.4 Changing Configuration Parameter Settings

When you run oamsys, the parameter settings specified in the board keyword files are stored in the NMS OAM database. All boards are then started in their specified configurations.

Parameters are communicated as keyword name/value pairs: AutoStart = NO. To change a parameter setting, you can:

• Use or modify one of the sample board keyword files corresponding to your country and board type. Specify the name of this new file in the File statement in oamsys.cfg and run oamsys again. Refer to the NMS OAM System User's Manual for information about board keyword file syntax.

• Specify parameter settings using the oamcfg utility. Refer to the NMS OAM System User's Manual for information about oamcfg.

• Create a new board keyword file, either with additional keywords, or keywords whose values override earlier settings.

• Specify the settings programmatically with OAM service functions. Refer to the NMS OAM Service Developer's Reference Manual for more information.

You may wish to:

• Change which software module files are downloaded to the board at startup. Refer to Section 3.4.2, Specifying Configuration File Location for more information.

• Specify board switching (Chapter 5).

• Configure CT bus clocking (Section 3.5, Configuring Board Clocking).

3.4.1 Board Keyword Files

A sample set of board keyword files are installed by the AG installation. These board keyword files are for the USA digital protocols:

File	Description
agpi4000.cfg	AG 4000C T
a4fgdpi.cfg	AG 4000C T, Feature Group D protocol
a4gdspi.cfg	AG 4000C T, Digital Ground Start protocol
a4opspi.cfg	AG 4000C T, Off-Premises Station protocol
a4ss5pi.cfg	AG 4000C T, Signaling System 5 protocol
a4wnkpi.cfg	AG 4000C T, Two-way Wink Start protocol
agi4t1pi.cfg	AG 4000C T, ISDN
agi4e1pi.cfg	AG 4000C E, ISDN

Sample board keyword files are shown in Section 3.7, Sample Board Keyword File. These board keyword files have many keywords in common. The differences in these files are related to the protocols, whose names appear as part of the name of the file. For more information about board keyword files, refer to the NMS OAM System User's Manual.

3.4.2 Specifying Configuration File Location

Files to be downloaded on the AG boards are specified with keywords in the AG board's keyword file. For example:

DLMFiles[0] = filename

If filename contains a path specification, NMS OAM searches for the file in the specified directory. Otherwise, NMS OAM searches for the file in the current working directory of ctdaemon. If the file does not exist in the current working directory, NMS OAM searches for the file in the search path defined by the AGLOAD environment variable.

3.5 Configuring Board Clocking

When multiple boards are connected to the CT bus, you must set up a bus clock to synchronize timing between them. In addition, you can configure alternative (or fallback) clock sources to provide the clock signal if the primary source fails.

For detailed information about clocking, refer to the NMS OAM System User's Manual.

Caution:

In systems containing a mix of CG 6000C boards and AG 4000C boards, NMS recommends that you use CG 6000C boards as the primary and secondary masters. Configure the AG 4000C board as a slave.

Refer to Section 3.5.3 for more information about clocking capabilities.

Boards in a CT bus system can be configured in one of the following modes:

Board Mode	Description
Primary clock master	Drives the primary timing reference for boards connected to the CT bus. It can switch between its two specified timing sources to maintain the primary timing reference. However, if both of its timing references fail, the primary master stops providing a timing source (and the secondary master then provides bus synchronization).
Secondary clock master	Drives the secondary timing reference. When the primary clock fails, the secondary master continues to drive the secondary clocks using a clock fallback source as its timing reference.
Clock slave	References its timing from the primary clock master and uses the secondary clock master as a fallback source of clock timing.
Standalone	Does not reference the primary or secondary master and, consequently, cannot make switch connections to the CT bus.

CT bus clock fallback establishes a redundant system of timing references for the CT bus. It does not create an autonomous clock timing environment. When clock fallback occurs, your application must intervene to reset system clocking before other clocking changes occur. If both the primary and secondary clock masters stop driving the clocks (and the application does not intervene), the boards default to standalone mode.

Certain board models have more flexible and reliable clocking capabilities than other models. In a mixed board system, choose the boards with the best capabilities as your primary master and secondary master. To determine which boards to use as masters, refer to the NMS OAM System User's Manual.

3.5.1 Clocking References

Boards that act as clock slaves derive their timing from signals driven by the clock masters (primary or secondary). Clock masters can drive the following reference clocks:

• A_CLOCK

• B_CLOCK

Primary clock masters can synchronize their own timing signals from the following sources:

• NETWORK

• NETREF

• NETREF2

• OSC

Secondary clock masters are hybrid systems. Their primary timing source must be A_CLOCK or B_CLOCK. Their fallback timing source must be one of the following sources:

• NETWORK

• NETREF

• NETREF2

• OSC

For further information about configuring clocks on the H.110 bus, refer to the NMS OAM System User's Manual and to the ECTF H.110 Hardware Compatibility Specification: CT Bus R1.0.

3.5.2 Clock Fallback

The CT bus supports a system of clock fallback that allows the system to use alternate timing references when one or more sources fail.

To enable clock fallback, set Clocking.HBus.AutoFallBack = YES. If clock fallback is disabled, the application must perform all clocking changes.

To implement clock fallback:

1. Configure a primary clock master to drive the CT bus clock (A clock or B clock) based on a network timing reference. All slave boards will synchronize their timing through this clock.

2. Configure a secondary clock master to use the signal from the primary clock to drive the alternate CT bus clock (in other words, if the primary master drives the A clock, configure the secondary master to drive the B clock based on the A clock, or vice versa).

3. Specify a fallback network timing reference for the secondary clock master to use in the event the primary clock master fails.

4. Configure all slave boards to specify the secondary clock master as their clock fallback source.

When the boards are configured in this way, the secondary clock master continues to drive the secondary clock (based on its own timing reference) if the primary clock master fails. Slave boards within the system fall back to synchronize their timing from the secondary clock master.

3.5.3 Clocking Capabilities

This section describes the rules and limitations that apply to setting up CT bus clocking on AG 4000C boards.

When an AG 4000C board is configured as the system primary clock master:

• The board's first timing reference must be set to a network trunk, a NETREF clock, or OSC. NMS recommends that you use a network trunk or OSC.

• The board's fallback timing reference must be set to a network trunk or a NETREF clock.

• If the board's first timing reference is a network trunk, the board's fallback timing reference must also be a network trunk.

When an AG 4000C board is configured as the system secondary clock master:

• The board's first timing reference must be the system's primary clock.

• The board's fallback timing reference must be a network trunk, a NETREF clock, or OSC.

When an AG 4000C board is configured as a clock slave:

• The board's first timing reference must be the system's primary clock.

• The board's fallback timing reference must be the system's secondary clock.

• If there is no secondary clock master for the system, the board's fallback timing reference must be set to OSC. In this case, if the first timing reference fails, the board will not be synchronized with the system until you reconfigure the board's clocking.

The following tables summarize the CT bus clocking capabilities of the AG 4000C board:

Clocking Capabilities as Primary Master

Capability	Yes/No	Comments
Serve as primary master	Yes
Drive A_CLOCK	Yes
Drive B_CLOCK	Yes
Available primary timing references:
Local trunk	Yes	The secondary timing reference must also be a local trunk.
NETREF1	Yes	The secondary timing reference must be NETREF2.
NETREF2	Yes	The secondary timing reference must be NETREF1.
OSC	Yes
Fallback to secondary timing reference	Yes
Available secondary timing references:
Local trunk	Yes	This is the only valid reference if the primary timing reference is a local trunk.
NETREF1	Yes	This is the only valid reference if the primary timing reference is NETREF2.
NETREF2	Yes	This is the only valid reference if the primary timing reference is NETREF1.
OSC	No
Slave to secondary master if both references fail	Yes

Clocking Capabilities as Secondary Master

Capability	Yes/No	Comments
Serve as secondary master	Yes
Drive A_CLOCK	Yes	If the primary master drives B_CLOCK, the secondary master drives A_CLOCK.
Drive B_CLOCK	Yes	If the primary master drives A_CLOCK, the secondary master drives B_CLOCK.
Available secondary timing references:
Local trunk	Yes
NETREF1	Yes
NETREF2	Yes
OSC	Yes

Clocking Capabilities as Slave

Capability	Yes/No	Comments
Serve as slave	Yes
Slave to A_CLOCK	Yes
Slave to B_CLOCK	Yes
Available fallback timing references:
A_CLOCK	Yes
B_CLOCK	Yes
OSC	Yes	The board is not synchronized until the application reconfigures the clock.

Other Clocking Capabilities

Capability	Yes/No	Comments
Drive NETREF1	Yes	This board can drive either NETREF1 or NETREF2, but not both at once.
Drive NETREF2	Yes	This board can drive either NETREF1 or NETREF2, but not both at once.
Operate in standalone mode	Yes

3.5.4 Configuring CT Bus Clocks With Keywords

The AG 4000C board keywords allow you to configure the board in the following ways:

• System primary clock master

• System secondary clock master

• Clock slave

• Standalone board

You can also use board keywords to establish clock fallback sources.

The following sections describe how to use board keywords to specify clocking configurations on multiple-board or multiple-chassis systems.

Configuring the Primary Clock Master

Use the following keywords to configure the primary clock master:

Keyword	Description
Clocking.HBus.ClockSource	Specifies the source from which this board derives its timing. Set this keyword to a network source (NETREF, NETREF2, or NETWORK).
Clocking.HBus.ClockMode	Specifies the CT bus clock that the board drives. This keyword must reference either the A clock (MASTER_A) or the B clock (MASTER_B).
Clocking.HBus.ClockSourceNetwork	Specifies the trunk number that the board uses as an external network clocking source for its internal clock. Trunk numbering is 1-based.
Clocking.HBus.AutoFallBack	Enables or disables clock fallback on the board.
Clocking.HBus.FallBackClockSource	Specifies an alternate timing reference to use when the master clock source fails. Set this keyword to a network source (NETREF, NETREF2, or NETWORK).
Clocking.HBus.FallBackNetwork	Specifies the trunk from which a fallback network timing source (for the clock fallback reference) can be derived.

Configuring the Secondary Clock Master

Use the following keywords to configure the secondary clock master:

Keyword	Description
Clocking.HBus.ClockSource	Specifies the source from which this board derives its timing. Set this keyword to the clocks driven by the primary clock master. For example, if the primary master drives the A clock, set this keyword to A_CLOCK.
Clocking.HBus.ClockMode	Specifies the CT bus clock that the secondary master drives. This keyword must reference the clock (MASTER_A or MASTER_B) not driven by the primary clock master.
Clocking.HBus.AutoFallBack	Enables or disables clock fallback on the board. Set this keyword to YES.
Clocking.HBus.FallBackClockSource	Specifies the alternate timing reference to use when the master clock does not function properly. Set this keyword to reference a network source (NETREF, NETREF2, or NETWORK).
Clocking.HBus.FallBackNetwork	Specifies the trunk from which a fallback network timing source (for the clock fallback reference) can be derived.

Configuring Clock Slaves

Use the following keywords to configure the clock slaves:

Keyword	Description
Clocking.HBus.ClockMode	Specifies the CT bus clock that the board derives its timing from. Set this keyword to SLAVE to indicate that the board does not drive any CT bus clock (although the board can still drive NETREF or NETREF2).
Clocking.HBus.ClockSource	Specifies the source from which this clock derives its timing. This keyword must reference the clock driven by the primary clock master.
Clocking.HBus.AutoFallBack	Enables or disables clock fallback on the board.
Clocking.HBus.FallBackClockSource	Specifies the alternate clock reference to use when the master clock does not function properly. For clock slaves, set this keyword to reference the clock (A clock or B clock) driven by the secondary clock master.

Configuring Standalone Boards

To configure a board in standalone mode so the board references its own clocking information, set Clocking.HBus.ClockMode = STANDALONE. The board can use either its own oscillator or a signal received from a digital trunk as a timing signal reference. However, the board cannot make switch connections to the CT bus.

3.5.5 Multiple Board System Example

The following example assumes a system configuration where three AG 4000C boards reside on a single chassis. The boards are configured in the following way:

Board	Configuration
Board 0	System primary bus master (driving the A clocks)
Board 1	System secondary bus master (driving the B clocks)
Board 2	Clock slave (clock fallback enabled)

This configuration assigns the following clocking priorities:

Priority	Timing Reference
First	Board 0, digital trunk 1. A network signal from a digital trunk provides the primary master clock source.
Second	Board 0, digital trunk 3. A network signal from a digital trunk provides the clock fallback source.
Third	Board 1, digital trunk 2. A network signal from a digital trunk provides the secondary master clock fallback source.

Figure 20 shows a multiple-board system with a primary and secondary clock master:

Figure 20. Sample Board Clocking Configuration

The following table shows keywords used to configure the boards according to the configuration shown in Figure 20:

Board	Role	Clocking Keyword Settings
0	Primary clock master	Clocking.HBus.ClockMode = MASTER_A Clocking.HBus.ClockSource = NETWORK Clocking.HBus.ClockSourceNetwork = 1 Clocking.HBus.AutoFallBack = YES Clocking.HBus.FallBackClockSource = NETWORK Clocking.HBus.FallBackNetwork = 3
1	Secondary clock master	Clocking.HBus.ClockMode = MASTER_B Clocking.HBus.ClockSource = A_CLOCK Clocking.HBus.AutoFallBack = YES Clocking.HBus.FallBackClockSource = NETWORK Clocking.HBus.FallBackNetwork = 2
2	Clock slave	Clocking.HBus.ClockMode = SLAVE Clocking.HBus.ClockSource = A_CLOCK Clocking.HBus.AutoFallBack = YES Clocking.HBus.FallBackClockSource = B_CLOCK

In this configuration, Board 0 is the primary clock master and drives the A clock. All slave boards on the system use the A clock as their first timing reference. Board 0 references its timing from a network timing signal received on its own trunk 1. Board 0 also uses its own trunk 3 as its clock fallback source. This means that if the network timing signal derived from trunk 1 fails, Board 0 will continue to drive the A clocks based on trunk 3.

If, however, both of the clocking signals used by Board 0 fail, then Board 0 stops driving the A clock. The secondary clock master (Board 1) falls back to a timing reference received on its own trunk 2, and uses this signal to drive the B clock. The B clock then becomes the timing source for all boards that use the B clock as their backup timing reference.

For this to take effect, all the clock slaves must specify the A clocks as their clock source and the B clocks as their clock fallback source.

3.6 Echo Cancellation

Echo cancellation is generally not required on digital trunks. It is disabled, by default, on the AG 4000C board. Because echo cancellation consumes many MIPS of DSP processing power, it may require a version of the AG 4000C board with more than 16 DSPs. Refer to Appendix B for specific configuration requirements.

Refer to the ADI Service Developer's Manual for more information on configuring echo cancellation on the AG 4000C board.

3.7 Sample Board Keyword File

This section presents the sample board keyword file agpi4000.cfg. The sample board keyword files are located in the ag\cfg subdirectory under the Natural Access installation directory. agpi4000.cfg shows the set of board keywords necessary to configure and start an AG 4000C T board. Follow the instructions in the file to configure an AG 4000C E board.

3.7.1 AG 4000C Board Keyword File

This is the agpi4000.cfg file:

#
#       AG configuration file for AG 4000
#

 Clocking.HBus.ClockSource = OSC
 Clocking.HBus.ClockMode = STANDALONE

# TCP files are shipped with the NMS CAS sub-package of Natural Access.
# Be sure that you installed the protocols that are specified below before
# trying to start a board with this configuration file.
 TCPFiles[0] = nocc.tcp           # "no trunk control" protocol
 TCPFiles[1] = wnk0.tcp           # 2-way wink protocol

# DSP (.m54) files to link in

 DSP.C5x.DSPFiles = callp.m54 dtmf.m54 mf.m54 ptf.m54 tone.m54 voice.m54

 DLMFiles[0] = gtp.leo
 DLMFiles[1] = voice.leo
 DLMFiles[2] = svc.leo

#--------------------------------------------------------------------------
# IF YOU ARE CONFIGURING AN E1 BOARD replace AMI_ZCS with HDB3 and D4 with  # CEPT to successfully boot the board. Consult AG 4000C documentation to     # determine proper configuration for your needs.
#--------------------------------------------------------------------------

# For AG 4000 Quad (comment other "NetworkInterface" lines if used)

 NetworkInterface.T1E1[0..3].LineCode = AMI_ZCS
 NetworkInterface.T1E1[0..3].FrameType = D4

# For AG 4000 Dual (comment other "NetworkInterface" lines if used)
#
# NetworkInterface.T1E1[0..1].LineCode = AMI_ZCS
# NetworkInterface.T1E1[0..1].FrameType = D4

# For AG 4000 Single (comment other "NetworkInterface" lines if used)
#
# NetworkInterface.T1E1[0].LineCode = AMI_ZCS
# NetworkInterface.T1E1[0].FrameType = D4