README.VpbConfig
================

Last updated: 7 Aug 2007


Important Note For Upgraders
----------------------------

Starting with the 4.1 release of the vpb-driver, some changes were introduced to
the configuration file options.  If you are updating from an earlier version,
please see the migration guide at the bottom of this file.


Introduction
------------

If you wish to use the Voicetronix OpenPRI card, or more than 1 type of
Voicetronix card, you will REQUIRE configuration files.  If you are only using
one type of analogue card and do not need to alter the default settings, then
using the configuration files is optional.

All configuration files for the VPB driver are kept in /etc/vpb.  The common
configuration file for all card types is vpb.conf.  The card specific files
are typically named vtcore.conf, openline.conf, or openpri.conf, though this
is configurable from vpb.conf.

The VpbConfigurator tool (found under src/utils in the driver source) is the
preferred method for initial setup of these configuration files.  This will
create a default configuration based on the hardware detected which can then
be fine tuned based on your individual requirements.


vpb.conf
--------

The vpb.conf file contains some basic information about the cards in the system,
and about the system itself.  It consists of 3 sections:

 The [general] section for general system information.

 The [configs] section provides locations for the card-specific configuration
 files (e.g. openline.conf, vtcore.conf, openpri.conf).

 The [cards] section lists the cards and the order in which they will be
 presented to the vpb API.


[general]
name      = general	<this is the type of the config file, always needed>
country   = 61		<IDD country code>
verbosity = 1		<turns on verbose logging, or set to 0 to turn it off>

[configs]
vtcore   = /etc/vpb/vtcore.conf		<config for OpenPCI/OpenSwitch cards>
openline = /etc/vpb/openline.conf	<config for OpenLine/OpenLog cards>
openpri  = /etc/vpb/openpri.conf	<config for OpenPri cards>

[cards]
0 = openpci:0		<card 0 is the 1st vtcore (OpenPCI) card (vtcore #0)>
1 = openswitch:1	<card 1 is the 2nd vtcore (OpenSwitch) card (vtcore #1)>
2 = openline:1		<card 2 is the 2nd OpenLine card (openline card #1)>
3 = openpri:0		<card 3 is the 1st OpenPri card (openpri card #0)>
4 = openline:0		<card 4 is the 1st OpenLine card (openline card #0)>
5 = openlog:2		<card 5 is the 3rd OpenLine card, and is in high-
                         impedance mode (openline card #2)>


vtcore.conf
-----------

The vtcore.conf file contains information about the OpenPCI and OpenSwitch cards
in your machine.  See the file "README.VTCore" for more details.

Here is an example, with comments:

[general]
name  = vtcore		<type of configuration file>
cards = 2		<number of cards configured in this file>

[card0]			<card name is "card<Number>" where Number starts from 0>
type = OpenPCI		<card type>

logging = 1		<channel is used for logging>

chan = 4		<apply the above settings for these channels>
chan = 5
chan = 6
chan = 7

[card1]			<card name is "card<Number>" where Number starts from 0>
type = OpenSwitch12	<card type>
dtmfms     = 70		<dtmf duration in ms>
cutthrough = 10.0	<lower record gain to use during dtmf detection>

chan = 0		<apply the above settings for these channels>
chan = 1
...
country = 1		<IDD country code> overrides the global setting
                                           for subsequent ports
chan = 11


openline.conf
-------------

The openline.conf file contains information about the OpenLine and OpenLog cards
in your machine.

Here is an example, with comments:

[general]
name  = openline	<type of configuration file>
cards = 2		<number of cards configured in this file>

[card0]			<card name is "card<Number>" where Number starts from 0>
type = OpenLine4	<card type>
bal1 = 0xf0		<codec balance 1 setting, optional>
bal2 = 0x5d		<codec balance 2 setting, optional>
bal3 = 0x70		<codec balance 3 setting, optional>
chan = 0		<apply the above settings for these channels>
chan = 1
chan = 2
chan = 3

[card1]			<card name is "card<Number>" where Number starts from 0>
type=OpenLine4		<card type>


openpri.conf
------------

The openpri.conf file contains the information about the OpenPRI cards in your
machine, and the settings required to connect to the ISDN line attached to it.
It MUST match information in the wanpipe configuration file and the
configuration of your ISDN line.

[general]
name=openpri            <type of configuration file>
channels=30             <number of channels configure in this file>
cards=1                 <number of cards configured in this file>

[card3]                 <card name is "card<Number>" where Number starts from 0>
priverbose=32           <verbosity of libpri, levels described in
                         src/libpri/readme.voicetronix>
name=wanpipe1           <name of card>
iftype=E1               <type of interface, E1 or T1>
node=client             <network or client interface, typically client>
protocol=euroisdn_e1    <protcol used (ni2,dms100,lucent5e,att4ess,euroisdn_e1,
                         euroisdn_t1,ni1,gr303_eoc,gr303_tmc)>
dialplan=national       <dial plan for number called (national,international,
                         local,private,unknown)>
localdialplan=national  <dial plan for calling number (national,international,
                         local,private,unknown)>
dchannel=16             <time slot that the D-channel is on>
encoding=alaw           <Default audio encoding, alaw, mulaw or raw, can be
                         set on a per channel basis>
channel1=wp1aft1        <channel or "time slot" interface name>
channel2=wp1aft1
...			<repeated for each 31 channels/time slots>
channel15=wp1aft1
channel16=wp1aft2
channel17=wp1aft3
...
channel29=wp1aft3
channel30=wp1aft3
channel31=wp1aft3


Migration Guide
---------------

Starting from vpb-driver 4.1, the following options are obsolete.  If present
they will be ignored:

channels  - This option has been removed from the general section and from all
	    card specific config sections except openpri.  It can be reliably
	    autodetected so specifying it explicitly can only be a source of
	    errors.

cardcount - This option has been removed.  The number of cards can be detected
	    in the absence of config files, and is specified implicitly by the
	    'cards' values in the type specific config files, so there is no
	    reason to maintain this value independently.

logdir    - This option was never implemented, there is no default log file
	    for the vpb-driver.  File paths may be specified explicitly.

channelX  - This option remains only for openpri cards.  Previously openline,
	    openlog and the vtcore cards also documented that it should be
	    used, but it is redundant for all of them, and was not supported
	    by others.  The channel type can be autodetected reliably so there
	    is no need for it to be specified explicitly.  To specify the
	    channels to apply 'fall through' options for, use 'chan = X'
	    instead, where X is the port number that previous options should
	    be applied to.
