Prosody installation guide

This document covers the steps required to install a Prosody TiNG distribution and run basic tests to ensure that everything is working correctly.

Getting Prosody onto your system

Normally, the Prosody package is installed using the Aculab Installer Tool (AIT), which has its own documentation. If you obtain it in another form (such as a special package sent by e-mail from Aculab), see Prosody TiNG packaging for the parts that might be supplied.

Note: whether you use the AIT or some other method, make a note of where on your system you install Prosody. If other people will be using Prosody on the system, make sure you pass on this information to them.

The directory structure

Prosody is packaged so that it all unpacks into a single directory and that directory's name includes the version number of the software. This means that you can unpack any number of packages or versions of the same package into the same directory without any of them adding or overwriting files in another version.

In the documentation for Prosody, references to a file or directory are often in the form:

The name $(TiNG) is used to refer to the directory created by unpacking a distribution so, for example, if you unpack a version called m123 and it creates a directory TiNG-distm123. then $(TiNG)/test/play.c would mean the file TiNG-distm123./test/play.c.

Some of the test programs use the APIs provided by the switch driver and the call driver, which come in separate packages. If you fetch them using the AIT, they will be put in directories beside the Prosody directory. For example, if you put everything in a directory called aculab, you might have directories:

If you do unpack things yourself, make sure you use this layout. The structure used inside the $(TiNG) directory is described in Prosody: layout of the distribution.

It is extremely useful to have a fixed name which refers to the current version of a package and, if you don't use the AIT, you will have to set this up yourself. On operating systems which support symbolic links (such as Solaris and Linux), make a link so that the names TiNG, call, and switch are each an alias for the version of each package that you want to use. For example, the commands

would be suitable if the versions you have are those given in the example above.

For Windows NT, which does not support symbolic links, the best alternative is to rename the directory that was unpacked.

For Windows 2000 / XP, you can try using directory junctions, which are very similar to symbolic links. Since no method is provided for creating one, you'll need either LINKD.EXE from the Windows 2000 Resource Kit, or the free alternative called Junction from Sysinternals (see http://www.sysinternals.com/utilities/junction.html).

Note for QNX: although QNX has symbolic links, there is an anomaly in their implementation which makes them difficult to use with TiNG on an NFS mounted volume. It is impossible to create a directory if its name is relative to a symbolic link:

	$ mkdir dir; ln -s dir sym; mkdir sym/x
	mkdir: sym/x: File exists

If you have your TiNG distribution mounted over NFS and you see mysterious failures from directory creation, check that none of the components in the path are symbolic links (e.g. in "/mnt/a/b/c/d/e/f" any of "a", "b", "c", etc). If they are, you need not avoid symbolic links - just create the needed directory manually.

The environment for Prosody

Prosody uses one environment variable. This allows components such as scripts to come in only one variant but work successfully across all operating systems. This environment variable is TiNGTARGET and should be set as follows:

For Linux only: Set TiNGTARGET to the value LINUX_V6. For example, use the shell commands:

	export TiNGTARGET=LINUX_V6

For QNX only: Set TiNGTARGET to the value QNX_PPC to build for QNX on Power PC, or the value QNX_X86 to build for QNX on x86. For example, use the shell commands:

	export TiNGTARGET=QNX_PPC

For Solaris only: If you want to build 32-bit programs and libraries, set the environment variable TiNGTARGET to the value SOL_32_V6. For example, use the shell commands:

	TiNGTARGET=SOL_32_V6
	export TiNGTARGET

If you want to build with the Forte compiler (formerly known as the Solaris Workshop compiler), use SOL_WS_V6 instead of SOL_32.

If you want to build 64-bit programs and libraries with gcc, use SOL_64_V6 instead of SOL_32_V6.

For Windows NT only: Set the environment variable TiNGTARGET to the value WINNT_V6. For example, at a DOS prompt, use:

	set "TiNGTARGET=WINNT"

Note that TiNGTARGET contains a lowercase i, so the quotes are necessary to prevent it being converted into a capital letter. It does not appear to be possible to set the environment variable from the control panel, because it changes the name into all capitals.

Using Prosody

If you want to run an application that uses original Prosody cards, then the Prosody device driver must be installed and running. Normally, if you are developing an application on a system you also need to run it on that system, but it's obviously possible to build an application on one system and run it on another, in which case the development system does not need to run the Prosody driver, and you can skip down to Preparing to build applications. Similarly, if you only need to support Prosody S and Prosody X, no driver is required.

Getting the driver running

The driver must be configured and started. This is done differently on each of the supported operating systems:

As soon as the driver is running, you can run test programs to verify the installation is correct. If you are installing Prosody to develop applications, you can build some of the test programs that come with Prosody; if you are only running pre-built applications, use whatever test programs that were supplied with them.

Preparing to build applications

Before building applications, you should build various libraries, tools, and test programs. They can be built using only command-line tools, as described in these steps:

Testing a typical installation

Normally, Prosody is installed on a system to allow development of software that uses Prosody. Appropriate testing for this situation consists of building test programs and running them. Since the previous step, Preparing to build applications, builds all the necessary programs, all that remains is to run them.

Testing Prosody S and Prosody X

For Prosody S and Prosody X, the suggested test is to play an RTP stream and record it. The test programs to do this are rtpplay and rtprec. Here is one way you can test recording:

when it runs it prints a message reporting the port number it has been allocated. For example, "RTP port = 10.0.0.1:16388, RTCP port = 16389". The RTP port is the one to which the rtpplay must send its data, so it would be set up like this to play the file "test.alaw":

Testing original Prosody cards

The test programs which do this are locplay and locrec. However, they use only Prosody itself and, therefore, make no connection to the outside world. If you are using Aculab cards which support E1/T1 trunks you can use the incall and outcall programs to set up calls, which can be connected to Prosody. The switch driver is responsible for such connections. A simple program, switch is included with Prosody which uses the switch driver to make such connections. Here is one way you can test recording:

Using locplay instead of locrec allows you to play back the recording you made, so you can hear if it is correct. Here are examples of the commands required with typical parameters.

The timeslot 48:0 is an arbitrary Prosody timeslot. Any free timeslot will work. The timeslot 32:1 is a typical timeslot used for incoming calls - the program incall shows which timeslot is used. Ths -Fa option selects A-law encoding of the recording and playback. This means you need to have downloaded the firmware modules outchan, inchan, recA, and playA to the Prosody processor. The -X80000 option limits the recording to 80000 octets, which is ten seconds.

Note! Since incall does not exit until the call is cleared, you will need to run it in a separate window.

The above example assumes you are using the first Prosody processor module on the first Prosody card, and also that you are using the first E1/T1 trunk on the first card. See the documentation for the various programs for how to specify different locations for these resources. Note that, if the Prosody resources are on a different card to the call control resources, you need to do twice as much switching - to switch each to and from the external bus (e.g. H.100) instead of connecting the call directly to Prosody. For example, you might need to do:

This assumes that the Prosody resources are on the card referred to as card 1 by the switch driver, while the call comes in on card 2. The H.100 timeslot 0:0 is used to carry data from Prosody to the call, and 0:1 is used to carry data from the call into Prosody.

Distributing applications that use Prosody

If you distribute applications that use Prosody, make sure you provide documentation describiing the firwmare they need, and any other information that may be needed to diagnose problems. If the applications are intended to be run on a system without development tools (i.e. a C compiler, at least) ensure your package includes pre-built copies of any Prosody test and diagnnostic programs that may be needed.