README.OpenPCI
==============

Last updated: 30 Apr 2008


OpenPCI Driver Installation
===========================

Prerequisites: it is assumed that before reading this document you
have the OpenPCI card already installed in a system and that you have
a working installation of Linux on that machine.  Some Linux system
administration skills are assumed, with at least sufficient knowledge
to compile and install software, including kernel modules, from source.
It is expected that you have an operational development environment,
including the GNU C and C++ compilers.

vpb-driver 4.2 requires OpenPCI cards to have firmware version 14.
Please contact Voicetronix to arrange a firmware upgrade if required.
The most recent vpb-driver release may be found at:
http://www.voicetronix.com/downloads.htm

The OpenPCI card requires the vtcore driver from this package.

To build and install the library and support files:

$ ./configure && make
$ su
# make install

Still working as the root user, generate the config files:

# ./src/utils/VpbConfigurator

This script will detect the cards you have in the system and ask
questions for anything it is unable to detect.  You will need to know
in advance:

- your country code
  This is the code used for dialling your country from overseas.  For
  example, if you are in Australia it will be 61, if you are in the UK
  it will be 44, if you are in the US it will be 1, and so on.  If you
  don't know it, you can look for it here:
  http://en.wikipedia.org/wiki/List_of_country_calling_codes

VpbConfigurator will write the files /etc/vpb/vpb.conf and
/etc/vpb/vtcore.conf. These files may be modified for user specific
requirements.  See README.VpbConfig for available options.

Load the kernel module:

# modprobe vtopenpci

You should see some initialisation messages reported to the system log
file (/var/log/messages or /var/log/syslog depending on your distro),
and the module should appear in the output of lsmod:

# lsmod | grep vtopenpci
vtopenpci              64564  0
vtcore                 30476  1 vtopenpci

Check that the card is not sharing interrupts with other devices:

# cat /proc/interrupts | grep vtopenpci
  5:  692527402          XT-PIC  vtopenpci
  7:  692566372          XT-PIC  vtopenpci
 10:  692511672          XT-PIC  vtopenpci
 12:  692750926          XT-PIC  vtopenpci

In the case of the machine above, there are four OpenPCI cards installed,
and each has its own interrupt line assigned (the first number before the
':' above).  If other device drivers are listed for any of these interrupt
lines (including other vtopenpci instances), then you will be likely to
have audio (and other signalling) corruption occur.  For machines being
deployed in production locations it is highly recommended that the kernel
module be loaded using `modprobe vtopenpci shareirq=0`.  This will cause
it (or any conflicting device if it is loaded first), to entirely fail to
load.  In such cases an obvious and catastrophic failure is preferable to
a subtle and hard to pinpoint one, but for initial testing, such a level
of strictness can be overkill and make it less obvious which devices are
in contention for the interrupt line.  How to resolve any such conflict
is machine and device dependent.  Some PC's allow you to change this from
their BIOS settings, for others you may need to place the card (or the
conflicting device) into some other PCI slot.


You are now ready to start developing your CT software, or installing
pre-developed software such as CT Server (available from Voicetronix).


-----------------------------------------------------------------------

Some Questions we've been asked more than once:
==============================================

Q: What do the little blinking lights on the back of the card tell me?

A: That depends on the type of the port:

 For FXS ports, the brightness of the LED is tied to the voltage that
 is currently being maintained on the line.  So they are off before
 the port is powered up, will blink a bit while it is being calibrated,
 and burn brightly when the port is powered up in the on-hook state.
 Usually you can see them get a bit dimmer when the line goes off-hook.

 For FXO ports, they will be off while the port is on-hook, and will
 light if the port is switched off hook.  This is independent of any
 voltage on the line and just shows the state of the circuit switch.


