# Fusion nailed-up sample: msppsamp

msppsamp demonstrates MSPP universal ports by setting up as many as 360 channels for voice or fax data transfer and can perform voice to fax switchover. Each MSPP channel processes and encodes/decodes voice and fax data. It transfers the data between PSTN (DS0) and IP (RTP or UDP) endpoints.

Running msppsamp performs the following tasks:

- Creates the maximum supported number of MSPP connections between endpoints at the IP network and the PSTN interfaces.

- Responds to incoming calls from the PSTN and enables MSPP connections.

- Provides a mechanism for controlling and querying the filters that make up MSPP connections.

- Initializes and loads the CG board (using oamsys) when invoked through the sample command file demo.cmd.

For an overview of an msppsamp test environment, refer to the msppsamp illustration.

This topic contains the following information:

- msppsamp overview

- Running msppsamp

- Details of operation

## msppsamp overview

Sets up and enables MSPP connections to transfer data from voice and fax calls across the gateway from one network to another.

#### Usage

demo

#### Featured functions

mspCreateEndpoint, mspCreateChannel, mspConnect, mspEnableChannel, mspSendCommand, mspDisconnect, mspDisableChannel.

msppsamp also uses NaturalAccess functions to initialize the MSPP API, and to set up event queues and contexts. It uses the NCC API to perform call control at the PSTN interface.

#### Requirements

msppsamp requires the test equipment to place and receive voice (and optionally, fax) calls over both CG board interfaces.

## Running msppsamp

#### Before you begin

Before running the demonstration program:

1. Edit the msppsamp demo.cmd file to specify the following information:

   Entry | Description | Allowed values
   -b boardnum | CG board number. Default is 0. | N/A
   -6 | Specifies that the connection will be conducted over an IPv6 link (without this argument, the default is IPv4). | N/A
   -d destinationIPaddress | IPv4 or IPv6 address of remote gateway where the voice or fax data is transferred. | IPv4 or IPv6 address.
   -D DTMFinband | Enable or disable inband DTMF carriage. Default is 0. | 0 - Disable inband DTMF carriage 1 - Enable inband DTMF carriage
   -E | Disables software echo cancellation processes performed on board DSPs. Set this option when using hardware echo cancellation (CG 6x6x Series boards only). | N/A
   -f numfaxcalls | Total number of fax channels for the program to run. | CG 6565C = Up to 480 ports CG 6565/E = Up to 240 ports CG 6060/C = Up to 120 ports
   -g vocodertype | Type of encoder/decoder filter to use. For fax, the -g field is ignored. Use commas with the supported vocoder types in the following combinations: Entering a single vocodertype without commas specifies a full duplex path that uses the specified encoder and decoder. Inserting a comma before the vocodertype (,711) specifies a simplex channel that uses only the voice decoder. Inserting a comma after the vocodertype (723,) specifies a simplex channel that uses only the voice encoder. Separating different vocodertypes with a comma (723, 711) specifies a duplex channel that uses one type of encoder (G.723) with another decoder (G.711). | 711 723 726 729 728 AMR EVR GFR L20 L30
   -i 0x xxxx | Specifies what events to display. Default is 0x0013. | bit 0 - All errors. bit 1 - NCC events for call setup and tear down. bit 2 - NCC miscellaneous events. bit 4 - All MSPP commands and events. bit 5 - MSPP Fax billing events. bit 6 - MSPP and RTCP Report events.
   -l localIPaddress | Local IPv4 or IPv6 address of the CG board Ethernet interface. | IPv4 or IPv6 address.
   -p protocol | Call control protocol to use (for example nocc, isdn, mfcr2, or wnk0). | Any protocol supported under Natural Access.
   -r RTCPsetting | Enable or disable RTCP report receiving and event generation. Default is 0. | 0 = Disable RTCP report events. 1 = Enable RTCP report events.
   -t startingtimeslot | Starting timeslot and port number. Default is 0. | 0 to 119 for E1 boards. 0 to 95 for T1 boards.
   -L lUDPportnum | Local UDP port to use as a base for the first voice channel. Unless another address is specified, lUDPportnum defaults to the address specified for the remote UDP port (the rUDPportnum specified with the -u option). The next channel increments this UDP port number by two. Therefore, for the default port, the first channel uses port 2000, and the next one uses 2002, then 2004, and so on. | UDP port number.
   -u rUDPportnum | Remote UDP port to use as a base for the first voice channel. The next channel increments this UDP port number by two. Therefore, for the default port, the first channel uses port 2000, and the next one uses 2002, then 2004, and so on. | UDP port number.
   -U tUDPportnum | UDP port to use as a base for the first T.38 fax channel. The next channel increments this UDP port number by two. Therefore, for the default port, the first voice channel uses port 2000, and the next one uses 2002, then 2004, and so on. | UDP port number.
   -n bcastEPs | Number of broadcast (simplex RTP send) endpoints to create plus 1. For example, to create seven broadcast endpoints, specify a bcastEPs of 6. | 0 to 7
   -v numvoicecalls | Total number of voice channels for the program to run. Default is 1. The total number of voice and fax calls cannot exceed 120. | 1 to 120.
   -m modemtransport | Enables modem or fax (DCE transport over a clear channel. Default is 0. | 0: Disables DCE transport 1: Enables DCE transport
   -g framequota | Number of frames per packet. For more information about frame quotas, refer to the Dialogic® NaturalAccess™ Fusion™ VoIP API Developer’s Manual. | Default is 2.
   -j jitterdepth | Jitter buffer depth. For more information about jitter depth, refer to the Dialogic® NaturalAccess™ Fusion™ VoIP API Developer’s Manual. | Default is 2 x framequota.

2. Edit one of the sample Fusion CG board keyword files so that it contains configuration information appropriate for the system.

3. Edit the fusion_oamsys.cfg file so that it specifies the following information for the system:

   Entry | Description
   Bus | Bus number of the CG board.
   Slot | Slot number of the CG board.
   File | File name of the CG board keyword file.

   Running the msppsamp command file (demo.cmd) automatically boots the CG board (using oamsys) according to the information specified in the modified fusion_oamsys.cfg file and the modified sample Fusion CG board keyword file.

#### Procedure

To run msppsamp:

1. Navigate to the nms\fusion\samples\msppsamp directory.

2. Edit the demo.cmd file (as described in Before you begin) to specify appropriate parameters for your system configuration and for desired program operation.

3. Enter the following command:

demo

4. Use test equipment to establish phone calls to the Fusion gateway system line interfaces. All incoming calls from the CG board are routed to the specified destination IP address.

msppsamp displays information about its activities as it performs data transfer and conversion tasks.

5. Enter any of the following options at the prompt. These commands take effect for all active ports:

   Option | Sub-option | Description
   A | Voice encoder filter commands.
   | 1 | Increase voice encoder filter gain.
   | 2 | Decrease voice encoder filter gain.
   | 3 | Enable or disable Voice Activity Detection (VAD).
   | 4 | Set IP side formatting for voice encoder filter (G.711 only).
   | 5 | Enable or disable DTMF/CED suppression filters.
   | 6 | Set encoding mode to online or offline.
   | 7 | Set encoder filter rate.
   | 8 | Change RTP payload ID in encoder filter.
   | 9 | Set DTMF mode.
   | S | Query voice encoder filter state.
   | P | Print voice encoder filter state.
   B | RTP endpoint filter commands.
   | 1 | Enable or disable RTCP events.
   | 2 | Enable or disable link status events.
   | 3 | Set number of frames per RTP packet.
   | 4 | Change RTP payload ID in RTP endpoint and voice decoder filters.
   | 5 | Change expected payload ID for DTMF packets.
   | 6 | Control MSPP DTMF events.
   | S | Query RTP endpoint state.
   | P | Print RTP endpoint filter state.
   C | Jitter filter commands.
   | 1 | Increase jitter buffer depth.
   | 2 | Decrease jitter buffer depth.
   | 3 | Enable or disable adaptive jitter mode.
   | S | Query jitter filter state.
   | P | Print jitter filter state.
   D | Voice decoder filter commands.
   | 1 | Increase voice decoder filter gain.
   | 2 | Decrease voice decoder filter gain.
   | 3 | Set IP side formatting for voice decoder filter (G.711 only).
   | 4 | Set decoding mode online or offline.
   | 5 | Change RTP payload ID on decoder and RTP endpoint.
   | 6 | Set DTMF mode.
   | 7 | Play DTMF digit.
   | S | Query voice decoder filter state.
   | P | Print voice decoder filter state.
   E | Echo commands.
   | 1 | Enable or disable echo cancel adaptation (performed through the ADI API).
   | 2 | Reset echo taps enable or disable (performed through the ADI API).
   | 3 | Enable or disable echo suppressor (performed through the ADI API).
   | 4 | Enable or disable echo cancel bypass (performed through the ADI API).
   | 5 | Query echo canceller status.
   F | CG board monitoring commands.
   | 1 | Query board Ethernet status.
   | 2 | Query board CPU usage.
   | 3 | Query the list of all IPv6 addresses.
   1 | T.38 fax relay filter commands.
   | 1 | T.38 fax relay filter configuration.
   | 2 | T.38 fax diagnostics.
   | S | T.38 fax relay filter query
   | P | Print fax relay session status.
   2 | T38UDP endpoint filter commands.
   | 1 | T.38 IFP encode configuration.
   | 2 | T.38 UDPTL encode configuration.
   | 3 | T.38 IFP decode configuration.
   | 4 | T.38 UDPTL decode configuration.
   | S | Query T38UDP endpoint state.
   | P | Print T38UDP endpoint state.
   S | Show or hide DPF event data (internal use only).
   | 1 | Suppress event data.
   | 2 | Show event data.

6. Press the ESC key to exit the program.

## Details of operation

msppsamp is a nailed up application because it performs no IP-side call control. Call data from each PSTN port is automatically directed to an IP address specified in the CG board keyword file used with oamsys.

msppsamp uses a single thread to wait for PSTN Call Control (NCC) events and asynchronous MSPP events (like the CED_DETECT event used in voice/fax switchover).

In addition, msppsamp creates a single NaturalAccess event queue to receive events for the following objects:

Objects | Description
MSPP API objects (endpoints and channels) | msppsamp creates three contexts per dedicated voice or fax channels (one channel, two endpoints), or five contexts per voice/fax switchover channel (two channels, three endpoints).
NCC API objects (lines and calls) | msppsamp creates one context per port for call control.

When you run demo.cmd, the program:

1. Initializes NaturalAccess.

2. Creates a NaturalAccess event queue.

3. Creates all MSPP endpoints and channels.

4. Enables MSPP channels as calls come in (MSPP endpoints are enabled by default).

5. Starts the CED tone detector that is needed for voice to fax switchover and transfers voice data across the channel.

For voice/fax switchover, the application waits for a fax CED tone from the PSTN endpoint. When a CED is detected, msppsamp sends a command to the DS0 endpoint to switch from voice to fax data transfer, disables the voice channel, and enables the fax channel.

For information about configuring T.38 fax filters, refer to the Dialogic® NaturalAccess™ Media Stream Protocol Processing API Developer's Manual.

Switching from fax data back to voice data is not supported. Consequently, when a voice channel is switched to fax with the -v option in the demo.cmd file, the channel must remain a fax channel.