Readme
Created 23/8/99
Voicetronix Voice Processing Board (VPB) Driver Software
www.voicetronix.com.au

NOTE
----

This file is for the Linux version of the driver.  Please
see Readme.win32.txt for the Windows version.

QUICKSTART
----------

1) edit src/vpbreglinux.cpp "STATICS" section:

a) If your card is a V4PCI
static char *vpb_firmware_file = FIRMWARE_FILE_PCI;
static int vpb_model = VPB_V4PCI;
b) If your card is a VPB4
static char *vpb_firmware_file = FIRMWARE_FILE_ISA;
static int vpb_model = VPB_VPB4;
c) If your card is a VPB8L
static char *vpb_firmware_file = FIRMWARE_FILE_ISA_VPB8L;
static int vpb_model = VPB_VPB8L;

Note: For ISA cards, also set default I/O base address #define BASE_ADDRESS,
the dip-switch settings are described in doc/vpb1.html

2) make
3) make install
4) cd to src
5) 'insmod vpb.o' - after this step a 'major number' will be printed to the
console, use this number in the next step.  
6) If you dont see anything printed out after 'insmod vpb.o', type 'dmesg',
and look for the 'major number'.
7) 'mknod /dev/vpb0 c 254 0' - note this example assumes the major number was 
254.
8) cd to unittest, try ./echo (VPB4 & V4PCI) - see echo.cpp for instructions

ALTERNATE WAY TO CONFIGURE DRIVER
----------------------------------

Environment variables can also be used to configure the driver for different
cards, as an alternative to compile-time mods to vpbreglinux.cpp.  All of the
environment variables are optional, if you specify none the compile time 
defaults will be used.  If you just specify one, defaults will be used for
the other parameters.

VPB_MODEL    [VPB4 | VPB8L | V4PCI]
VPB_FIRMWARE [e.g. /etc/vpb/vpbmain_pci.out]
VPB_BASE     [hex base address, e.g. 0x310]

e.g. (bash shell) place the following in your ~/.bash_profile:

VPB_MODEL=V4PCI
export VPB_MODEL

SETTING DIAL AND BUSY TONES VIA ENVIRONMENT VARIABLES
-----------------------------------------------------

In this initial version, we can only set one tone (either DIAL or BUSY) using
the VPB_TONE env variable.  The main reason for this feature is to allow users 
to program the busy tone detector for different PBXes without having to modify
and recompile any code.

The format of the VPB_TONE env variable is described on line 63 of 
src/envtone.cpp.  This assumes you know the parameters of the tone. See below
if you don't.

The tone detectors can also be programmed using the VPB API function calls.  
For more info on this and tone detection in general please see the html help 
files in the doc directory.

To determine the parameters of a tone, this is what I do:

- sample the tone using unittest/recwav.  For example to sample the busy tone,
dial the port, start recwav, then hangup the phone.  To sample dial tone just
run recwav without dialling the port from another extension.  Run recwave for
about 30 seconds on pulsed tones so that you get at least 10 repetitions - 
this helps later with testing.

- use a waveform editor to view the tone and determine it's frequency and
  on-time (on-tiem is only valid for pulsed tones such as busy only, dial 
  tones usually stay on).  I use a Windows shareware editor called Goldwave 
  (www.goldwave.com).  You can determine the frequency of the tone in Goldwave
  by clicking on the waveform wiindow in the "Device Controls window", this 
  will give you a spectral view of the tone.  Each division is 400Hz.  There 
  may be a similar tool available for Linux.

- For a pulsed tone, determine the frequency and on-time.  For continuous
  tone such as dial, just the frequency is required.

- Try setting the bandwidth to 100Hz, if that doesnt work, try 200Hz.

- To test your tone detector, the unittest/tonedebug program is useful.  This
  program can play your sampled tone, while at the same time it tries to 
  detect the tone using the parameters you have determined.  These parameters
  can be entered on the command line of tonedebug, so testing variations of
  the tone detector parameters is easy.  Note that this program must run
  without _any_ phone lines connected to the card - it replays the tone
  you sampled, while simultaneously sampling the same signal to the prototype
  tone detector you are testing.

- Once you are happy with the tone detector (for example, it detects all 10
  repetitions of the tones you sampled), you can then set the env variable
  to desctibe the tone, and run your main application.

Examples:

1) Dial tone.  The frequency is 500Hz, and we select a bandwidth of 100Hz. We
would like the tone detector to "fire" after 1 second (1000ms) of continuous 
dial tone. The dial tone we sampled with recwav is in the file mydial.wav

In the unittest dir:

./tonedebug -c 500 100 1000 -w mydial.wav -t dial

which will produce:

[00] Tone Detect: Dial
[00] Play End

2) Busy tone.  The frequency is 425Hz, and we select a bandwidth of 200Hz.
By inspecting the wave file we determine that this pulsed tone is on for 375ms.
The wave file is called mybusy.wav.

./tonedebug -p 425 200 375 -w mybusy.wav -t busy

which will produce something like:
[00] Tone Detect: Grunt
[00] Tone Detect: Busy
[00] Tone Detect: Busy
[00] Tone Detect: Busy
[00] Play End

In this case, all three busy tones sampled were detected OK.  The "grunt" tone 
is a special tone detector that just senses energy on the line.

To then set the busy tone detector using an env variable (bash shell):

export VPB_TONE=BUSY,P,425,200,375


HISTORY
-------

2.1.8
2/11/01
- added a couple more unit tests for conferencing and running two vpb8ls
- added a way to prog tone detectors via via env variables, saves recompiling
driver for new tones (esp useful for Openh323 pstngw)

2.1.7
19/10/01
- changed license to LGPL in response to several requests
- moved install destination of libvpb.a from .usr/licb to /user/local/lib

2.1.6
- can now play .au files (no record yet)
- fixed bug that caused fast PCs to occasionally hang when DSP started

2.1.5
2/10/01
- CID support was modified as it was interferring with some UTs, and not
working in North America.  UT program cidtest.cpp modified and tested
on North American machine via ssh.  Worked OK.
- Auto detection for number of PCI cards under Linux.  Coded but not tested
under Win32.
- init script written by David Sugar (src/vpb.init) - Thanks David!
- new unit tests for testing echo canceller on remote machines

2.1.4
Sep 01
Windows NT/98/2000 driver port for V4PCI.
Support for Linux 2.4 kernel (Thanks Fred Leeflang and David Sugar)

2.1.3
env variable support to specify card, firmware, base.

2.1.0
5/6/01 DR
Changed version number to better reflect the merging of the 2.0.x and 1.6.y 
driver libraries.
Modified the PCI & hi-echo ISA firmware files to not crash under high load.

1.6.8
28/5/01 DR
Added first pass html documentation to doc directory.
Merged vpb-2.0.4 driver to support Bayonne (www.bayonne.cx).  Previously
the 2.0.x & 1.6.x driver code was incompatible.
Caller ID for PCI card

1.6.6
22/4/01 DR
Flattened directory structure
Updated echo cancellation demo programs in unittest

1.6.5
2/03/01 DR
Merged PCI card support
Lots of unit test programs
VPB8L support, AGC enabled for VPB8L

1.6.4
3/11/00 DR

Fixed bug in vpbtimer that removed timer from list after event posted.  
Should be removed from list before posting to work correctly with ACS.

1.6.3

This release has a mod the Critical Section (Mutex implementation), to fix
a bug that gave different performance betwwen NT & Linux.  Makefile also
modified to install vpbmain.out in /etc/vpb instead of /etc

1.6.2

The kernel module now allows one to specify an override for the major
device number.  The makefile for the driver has been fixed to pass
nessisary compiler options.  Finally, some support for detecting and
(hopefully) playback of ".au" files has been started.

Amended 01/10/2000

1.6.1

This source release is based on the 1.6 Voicetronix VPB4 driver and
includes the Voicetronix update for newer 2.2.1x kernels.

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

Copyright (C) 1999-2001 Voicetronix Pty Ltd

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.