Voicetronix Programming Guide

Voicetronix Programming Guide
Legal Notice
Table of Contents
Introduction
Programming
Initialization and Shutdown
Error Handling
Events
Playing and Recording Audio
DTMF and Programmable Tone Generation
Tone Detection
Automated Tone Training
Timers
WAVE File and AU File Functions
Get Digits Functions
Call Progress Functions
VOX Functions
Pip Functions
Miscellaneous Functions
Function Reference
Introduction
This document describes how to program Voicetronix computer telephony cards using the
Voicetronix Voice Processing Board API (VPBAPI).
Unless otherwise stated, the term VPB (Voice Processing Board) will refer to all Voicetronix
cards. The VPBs are programmed via the VPB Application Programmer Interface, a set of C
callable functions provided as a Windows 32 bit DLL (Windows), or a user-mode library
(Linux & FreeBSD) . This will be referred to as the VPBAPI, or just API.
For installation details please see the README file for your operating system, located in vpb-
driver/.
Please refer to the README files, driver source code, and code examples for the latest
information on using Voicetronix cards.
FCC Compliance Statement for OpenLine4: Complies with Part 68 Rules, Certification
#VTX-AUS-46040-PT-T, AC-REN 0.6B, DC-REN NA.
Next >>>
Programming

<<<
Previous Next >>>
Programming
Introduction
The Voicetronix cards are programmed via the VPB Application Programmer Interface
(VPBAPI, or just API). This is a set of C callable functions. The following sections describe
the VPBAPI in detail, and also include examples of the API functions in action. It is
recommended that the user browse the header file vpbapi.h to gain an overview of the API.
Compiling with the VPBAPI

Linux and FreeBSD
Simply link libvpb.a with your application:
$ gcc test.cpp -o test -Wall -g -lvpb -pthread -lm
Windows
1. Create a new project (e.g. Win32 Console Application) and insert your source files.
2. Project-Settings-C/C++:
o set "Category" to "Code Generation"
o set "Use run-time library:" to "Debug Multithreaded"
3. Project-Settings-Link:
o To the "Object/library modules" add ../debug/libvpb.lib (you might need

to change the path to libvpb.lib, depending on where you create your
project).
4. Build your project.
5. Make sure libvpb.dll and plxapi.dll are in your path before running. One way is
to set the Project-Settings-Debug-Working Directory to a directory containing the
DLL, or place the DLL in a directory in your path (e.g. c:\winnt\system32)
6. Set the path for the firmware. The firmware is called vpbmain_pci.out, and is in
vpb-driver/firmware/. There are two ways to set the path:
o Modify vpbreg.cpp, change the #define FIRMWARE_FILE_PCI to your path
and recompile libvpb.dll (see Readme.Win32.txt for information on how
to recompile the driver).
o Set an environment variable VPB_FIRMWARE to the path to the firmware file.

Under NT go to control panel-system-environment. After setting the env.
variable, you will need to restart MSVC before running so that the new env.
variable is available to MSVC.
7. You should now be able to run your program from MSVC.
<<< Previous Home Next >>>
Voicetronix Programming Guide Initialization and Shutdown

<<< Next
Previous >>>
Initialization and Shutdown

This section describes the "housekeeping" functions used to initialize and shutdown a
Voicetronix card. The initialization function vpb_open() must be called before any other API
functions will work:
Example 1. Initialization and Shutdown
void main() {
handle = vpb_open(1, 2);
vpb_close(handle);
}
This program demonstrates initialization and shutdown of a single channel, (number 2), on
the first board in the system. Each channel (or port) of the card has an associated number. On
the OpenLine4 card, channel 1 is the port furthest from the motherboard. Port 4 is closest to
the motherboard.
The vpb_open() function returns a handle to the open channel. This handle then provides a
reference to all other operations with this channel. A call to vpb_open() is required for each
channel that is to be used. If a channel is not opened, then no operations can be performed
with that channel.

Programming Error Handling
<<<
Previous Next >>>
Error Handling
Under certain conditions the API functions will be unable to successfully execute. In this case
an error condition will occur that requires handling by code outside of the API. The API
provides three modes of error handling:
 Exceptions
 Error codes
 Debug
The current error mode is set using the vpb_seterrormode() function. The default error
mode is Debug.
Debug
If an error occurs in this mode, the program stops execution immediately and prints an error
message. This is useful during debugging as it brings any problems to the programmer's
immediate attention. However, such behavior is obviously not desirable in release versions of
the software. Note that this mode is only suitable for console mode programs, it will cause the
program to hang when used with a windows program.
Error Codes
In this case the function returns an integer corresponding to the nature of the error. The
convention used by the API is that positive numbers and zero indicate successful function
completion, and negative numbers represent an error condition. The error codes for the API
functions are listed in vpberr.h. There are other, undocumented error codes that lower levels
of the API software may return, but these are not defined in vpberr.h. These errors should
not occur during normal operation. To convert an error code into a more helpful error string,
use vpb_strerror().
Exceptions
Exceptions are a form of error handling supported by C++. When an error occurs, an
exception is "thrown". In the case of the VPBAPI , the exception is a class VpbException
that contains information describing the error. The code member of the class corresponds to
an error number defined exactly the same way as in the error code error handling method.
The other members contain strings describing the API function that generated the error and a
brief translation of the error code. The user must provide code to catch the exception at some
level in their program. The advantage of exceptions is that it is not necessary to trap errors at
every API call, which can become tedious from a programming point of view, especially for
API calls deep within nested function calls. Consider the following code fragments, first
using error codes:
Example 2. Error Handling Using Error Codes
vpb_seterrormode(VPB_ERROR_CODE);
// Attempt to open channel 1
if ((handle1 = vpb_open(1,1)) != VPB_OK) {

printf("Error, code = %d\n",handle1);
exit(0);
}
// Attempt to open channel 2
if ((handle2 = vpb_open(1,2)) != VPB_OK) {

printf("Error, code = %d\n",handle2);
exit(0);
}
And now using exceptions:
Example 3. Error Handling Using Exceptions
try {
vpb_seterrormode(VPB_EXCEPTION);
handle1 = vpb_open(1,1);
handle2 = vpb_open(1,2);
}
catch (VpbException v) {
printf("Error, code = %d, s = %s, api func = %s\n", v.code,
v.s, v.api_function);
exit(0);
}
Using exceptions enables the programmer to send all run time errors to a single point in the
code, removing the need for handling errors after every API call. If the current function does
not have try/catch exception handling, then the compiler aborts the current function, climbing
up the "call stack" until an exception handler is found in a calling function. If no exception
handler is found in the calling functions, the program aborts. For more information on
exceptions, see a C++ text, or your C++ compiler on-line documentation.
Initialization and Shutdown Events

<<< Next
Previous >>>
Events
The VPBAPI uses an event driven programming model. There are two types of events, solicted, and
unsolicited. The following functions deal with events:
vpb_disable_event()
vpb_enable_event()
vpb_get_event_mask()
vpb_set_event_mask()
vpb_get_event_async()
vpb_get_event_sync()
vpb_get_event_ch_async()
vpb_get_event_ch_sync()
vpb_put_event()
Solicited events are generated as a response to a previous API function call. For example,
when vpb_play_file_async() is called, a solicited event of type VPB_PLAYEND is generated
when the file has finished playing.
Unsolicited events are generated in response to external conditions, for example due to a
DTMF tone being detected by the card.

Error Handling Playing and Recording Audio
<<<
Previous Next >>>
Playing and Recording Audio

Summary of Play Functions
The API play functions are listed below:
vpb_play_file_sync()
vpb_play_file_async()
vpb_play_voxfile_sync()
vpb_play_voxfile_async()
vpb_play_terminate()
vpb_play_buf_start()
vpb_play_buf_sync()
vpb_play_buf_finish()
vpb_play_set()
vpb_play_set_gain()
vpb_play_get_gain()
The VPBAPI supports the playing of WAVE and VOX and AU files. It also accommodates
the playing of buffers from memory via the user defined play routines. The play functions can
be configured to terminate when a DTMF digit is received using vpb_play_set(). The play
functions may be prematurely stopped using vpb_play_terminate(). The API provides a
function to alter the VPB audio out levels within the range of -12 to 12 dB (0.1dB resolution).
This is accomplished by vpb_play_set_gain().
Summary of Record Functions
The API record functions are listed below:
vpb_record_file_sync()
vpb_record_file_async()
vpb_record_voxfile_sync()
vpb_record_voxfile_async()
vpb_record_terminate()
vpb_record_buf_start()
vpb_record_buf_sync()
vpb_record_buf_finish()
vpb_record_set()
vpb_record_set_gain()
vpb_record_get_gain()
The VPBAPI supports the recording of audio files. It also accommodates the recording of
audio to memory via the user defined record routines. The record functions can be configured
to terminate when a DTMF digit is received using vpb_record_set(). The record functions
may be prematurely stopped using vpb_record_terminate(). The API provides a function
to alter the VPB audio in levels within the range of -12 to 12 dB (0.1dB resolution). This is
accomplished by vpb_record_set_gain().
Playing Audio
The API functions for playing audio are divided into two groups; file-based functions, and
buffer-based functions.
The file-based play functions are designed to make playing files straightforward. These
functions support WAVE and AU files sampled at 8 ksamples/s only, playing files that follow
the WAVE and AU file specification including for 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law,
and 4-bit OKI-ADPCM.
There are also file-based play functions that support VOX (headerless) audio files sampled at
8 ksamples/s including; 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law and 4 bit OKI-ADPCM.
The buffer-based play functions allow the development of custom play routines in situations
where the file-based functions are inappropriate, for example, when playing buffers from
memory or when using non WAVE/VOX file formats:
vpb_play_buf_sync()
Compression (encoding) mode used to store samples

Mode Description
VPB_LINEAR 128kbit/s, 16 bit linear, 8kHz sampling rate
VPB_ALAW 64kbit/s, A-Law companded
VPB_MULAW 64kbit/s, Mu-Law companded
VPB_OKIADPCM 32kbit/s, Oki-ADPCM, 4 bit, 8kHz sampling rate

Mode Description
VPB_OKIADPCM24 24kbit/s, Oki-ADPCM, 4 bit, 6kHz sampling rate
Recording Audio
The API functions for recording audio are divided into two groups; file-based functions and
buffer-based functions.
The file-based record functions are designed to make recording files straightforward. The
functions support WAVE files sampled at 8 ksamples/s, recording audio to files that follow
the WAVE file layout specification including 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law and 4-
bit OKI-ADPCM.
There are also file-based record functions that support VOX audio files sampled at 8
ksamples/s including; 16 bit Linear, 8 bit A-Law, 8 bit Mu-Law and 4 bit OKI-ADPCM.
The user definedbuffer-based record functions allow the development of custom record
routines in situations where the utility functions are inappropriate, for example, when
recording buffers to memory or when using non WAVE/VOX file formats:
Events DTMF and Programmable Tone

Generation

<<< Next
Previous >>>
DTMF and Programmable Tone
Generation
The following functions support tone generation on the VPB:
vpb_dial_async()
vpb_dial_sync()
vpb_settone()
vpb_gettone()
Tones (including DTMF) tones are generated on a channel using the vpb_settone()
function. All of the standard DTMF tones are defined at initialization. Other user defined
tones can be programmed at any time using the vpb_settone() function. The standard
DTMF tones can also be reprogrammed using the vpb_settone() function. The tone
generator parameters are constant across all VPB channels, they are not programmable on a
channel by channel, or board by board basis. Up to 10 programmable tones can be defined,
giving a total of 26 tones including the standard DTMF tones. Each tone can consist of up to
3 frequency components, each with independent amplitude, specified in dB with respect to
the overload level of 0dB. There are limits in the tone generator parameters. Attempting to
program a tone outside of these limits will generate an error.

Playing and Recording Audio Tone Detection
<<<
Previous Next >>>
Tone Detection
The following functions support programmable tone detection:
vpb_settonedet()
vpb_gettonedet()
vpb_debug_tonedet()
When a tone is detected, a VPB_TONEDETECT event is placed on the event queue with the tone
identifier placed in the data element of the event structure. There are 3 pre-defined tones,
VPB_DIAL (dial tone), VPB_RINGBACK (ringback), and VPB_BUSY (busy tone). These are
configured for standard tones and may be redefined if desired to suit the actual switch to
which the VPB is connected. Up to VPB_MD (a #define in vpbapi.h) tone detectors can be
defined for each channel of each VPB. Counting the 3 pre-defined tones, VPB_MD-3 new user
defined tones are available for the user, or the pre-defined tones may be redefined to give a
total of VPB_MD user defined tones. To redefine a pre-defined tone, just specify the pre-
defined tone identifier in the tone_id parameter of the VPB_DETECT structure when
programming the tone.
Note: The VPB_MD (#define in vpbapi.h) is set by Voicetronix and should not be modified
by the user. Up to ten programmable tones (including the pre-defined tones) are available for
the user. The tone detectors of each channel are independent of the tone detectors of other
channels. Thus each channel must be programmed independently with the
vpb_settonedet() API function.
Programming the Tone Detectors
Tone detectors (either DIAL, BUSY, RINGBACK, GRUNT, or user [5..9] tone detectors) can
be programmed at driver start up using the VPB_TONE env. variable. The main reason for
this feature is to allow users to program the busy tone detector for different PBX models
without having to modify and recompile any code.
The format of the VPB_TONE env. variable is described in src/envtone.cpp.
The tone detectors can also be programmed using the VPBAPI function calls. For more
information on this and tone detection in general please see the next section.
To determine the parameters of a tone:
1. 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.
2. Use a waveform editor to view the tone and determine it's frequency and on-time (on-
time is only valid for pulsed tones such as busy only, dial tones usually stay on). I use
a Windows shareware editor called Goldwave. You can determine the frequency of the
tone in Goldwave by clicking on the waveform window in the "Device Controls
window", this will give you a spectral view of the tone. Each division is 400Hz. There
may be similar tools available for Linux.
3. For a pulsed tone, determine the frequency and on-time. For continuous tone such as
dial, just the frequency is required.
4. 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.
5. Try setting the bandwidth to 100Hz, if that doesn't work, try 200Hz.
6. 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 describe the tone, and
run your main application.
Examples
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
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] 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
See also src/envtone.cpp for more information.
More Detail on Programming the Tone Detectors
The tone detection algorithm is split into two phases. The first phase checks an incoming
signal to determine if its signal parameters fit the templates defined in the tone detector, for
example, the frequency, bandwidth, level, and signal to noise ratio (SNR). The second phase
looks at the on-off timing of the signal, or cadence information. If both the signal parameters
and the cadence parameters match, an event is posted.
Each programmable tone has a unique identifier, i.e. a 16 bit integer that is placed in the data
element of the event when the tone is detected. The value of the tone identifier is not
important, as long as it is unique. If vpb_settonedet() is called with a non-unique identifier
(one which has been used before), then that programmable tone is redefined. If
vpb_settonedet() is called with a unique identifier (one which has not been used before),
then a new programmable tone is defined.
The structure VPB_DETECT is used to define a programmable tone. Single or dual frequencies
can be specified, each with independent frequency, amplitude, and bandwidth. In addition,
the allowable twist for dual tones (difference in level between the two tones) can be defined.
Attempting to define a tone outside of the tone detector limits will cause an error.
Signal Detection Algorithm
For a single frequency tone to pass the signal processing phase, the following conditions must
be true:
1. The level of the tone in the band specified by the frequency (freq1) and bandwidth
(bandwidth1) must be above the minimum level (minlevel1).
2. The signal energy must be greater than the rest of the energy in the received signal by
the specified signal to noise ratio (snr).
3. If the above conditions are met, then the signal is declared detected and is passed to
the cadence detection stage for cadence analysis. For a dual frequency tone to pass the
signal processing phase, the following conditions must be true:
4. The level of the first frequency component in the band specified by the frequency
(freq1) and bandwidth (bandwidth1) must be above the minimum level (minlevel1).
5. The level of the second frequency component in the band specified by the frequency
(freq2) and bandwidth (bandwidth2) must be above the minimum level (minlevel2).
6. The total signal energy in both bands must be greater than the rest of the energy in the
received signal by the specified signal to noise ratio (snr).
7. The difference in the energies of the two frequency components must be within the
allowed twist.
If the above conditions are met, then the signal is declared detected and is passed to the
cadence detection stage for cadence analysis.
Cadence Detection Algorithm
The cadence detection parameters of the tone detector are defined by constructing a state
machine for each tone detector. The state machine is defined by a state transition table (stran),
and the number of states (nstates). The state transition table consists of an array of VPB_STRAN
structures. The state machine begins in state 0 and progresses to the next state when the state
transition requirements are met for that state. When the final state transition occurs, an event
of type VPB_TONEDETECT is posted on the API event queue. A maximum of VPB_MS (#define
in vpbapi.h) cadence states are allowed for each state machine.
There are three types of state transitions:
VPB_TIMER. A state transition occurs when no change (transition) in the signal occurs for the fire
time (tfire) in milliseconds. If a transition occurs before time tfire, the state machine is reset to
state 0. The VPB_TIMER transition provides a way to measure the on time of signals without cadence,
for example continuous dial tones.
VPB_DELAY. It waits the desired time, tfire ms and goes to the next state. The VPB_DELAY
transition provides a way to wait a desired time irrespective of any signal transitions.
VPB_RISING. A state transition occurs on the rising edge of the signal detection, that is, when the
signal goes from a non-detected to detected state. The state transition occurs if the time spent in this
state is between the minimal (tmin) and maximum (tmax) time in milliseconds. If at the rising edge
the time spent in this state is not between tmin and tmax ms, the state machine is reset to state 0. If
tmin and tmax are both set to 0, then a state transition occurs on the rising edge of the signal,
regardless of the time spent in this state. The VPB_RISING transition provides a way to determine
how long the signal was off.
VPB_FALLING. A state transition occurs on the falling edge of the signal detection, that is when the
signal goes from a detected to non-detected state. The state transition occurs if the time spent in this
state is between tmin and tmax ms. If at the falling edge the time spent in this state is not between
tmin and tmax ms, the state machine is reset to state 0. If tmin and tmax are both set to 0, then a
state transition occurs on the falling edge of the signal, regardless of the time spent in this state. The
VPB_FALLING transition provides a way to determine how long the signal was on.
Programmable Tone Detector Tips
The cadence state machine approach has the advantage that non-periodic or variable cadences
may be detected, for example a tone that has a long on period, then a short on period. To
detect several cycles of a periodic cadence pattern, for example 3 on/off cycles of a busy
tone, just repeat the cadence state detector rising and falling edge transitions the desired
number of times, up to the VPB_MS (#define in vpbapi.h) limit.
When designing/debugging a tone detector, start with a simple cadence detector, for example
just a single rising edge state. Adjust the signal detection parameters first, then add and test
the extra cadence states one at a time. This will identify any problems with the last cadence
state added. Don't forget to modify the nstates parameter in the VPB_DETECT structure as extra
states are added.
When designing/debugging a tone detector, start with wide bandwidths (several hundred Hz),
and low level thresholds (say -40 dB), then gradually tighten (reduce bandwidth, increase
level) these parameters to increase the robustness of the tone detector. Amplitude modulated
signals have wider bandwidths than pure sinusoids, and their amplitudes move up and down
with the modulation frequency. Amplitude modulated signals may therefore need lower level
thresholds than unmodulated tones. As a rule of thumb, use a bandwidth about four times as
wide as the modulating frequency, for example, 100 Hz for a 25 Hz modulating frequency.
The level threshold may need to be very low to detect the signal through the low level
periods, so try -40 dB as a starting point for the level parameters.
Programmable Tone Detector Examples

Continuous dial tone at 425 Hz, amplitude modulated at 25 Hz
This discussion refers to the toned_dial variable below.
This tone is amplitude modulated at 25 Hz, which spreads the bandwidth approximately 25
Hz either side of the main frequency component. A bandwidth of 100 Hz is used to be sure
that all of the dial tone energy is captured, although only 50 Hz is strictly necessary. The level
of amplitude modulated signals can also be quite low (it varies up and down with the
modulating signal), so a low amplitude threshold of -40dB is used. The tone contains only a
single frequency component so the 2nd frequency parameters are set to 0, which instructs the
tone detector software to ignore the 2nd frequency.
The signal to noise ratio (SNR) was set to 10 dB so that the detector requires most of the
energy in the signal to be contained in the 100 Hz bandwidth. This helps to reduce false
triggering, for example by a speech signal that may have energy around 400 Hz.
There are two cadence states specified. The first looks for a rising edge in the signal detection
logic. No time parameters are specified, so only the rising edge (from non-detected to
detected signal condition) is required to move the state machine to the second state.
The second state is a VPB_TIMER state. This timer "fires" when the signal has been detected
for 2000 ms. If the signal disappears in this time, the state machine is reset to the first state
and no event is posted. If the signal continues uninterrupted for 2000 ms, an event is posted
to the API event queue and the state machine resets itself to state 0. The event will contain
VPB_DIAL in the data member of the VPB_EVENT structure.
Note that the timer state provides an additional level of "filtering", as the signal must be
continuous and uninterrupted for 2000 ms. Any non-valid signals are unlikely to meet the
signal detection conditions for this time, and will be discarded by the state machine.
Example 4. toned_dial for 425Hz continuous dial tone, modulated at 25Hz
static VPB_DETECT toned_dial = {

2, // number of cadence states
VPB_DIAL, // tone id
1, // number of tones
425, // freq1
100, // bandwidth1
0, // freq2, N/A
0, // bandwidth2, N/A
-40, // level1
0, // level2, N/A
0, // twist, N/A
10, // SNR
40, // glitch duration 40ms
VPB_RISING, // state 0
0,
0,
0,
VPB_TIMER, // state 1
2000,
0,
0
};
Austel Busy Tone 425 Hz or 400 Hz, 375ms on, 375 ms off
This discussion refers to the toned_austel_busy variable below.
The Austel busy tone has two possible frequencies, 400 or 425 Hz, so a bandwidth of 100 Hz
has been used to make sure both possibilities are within the bandwidth of the signal detector.
As the signal is a single unmodulated tone, the amplitude will be relatively stable, so we can
set a fairly high cut off level of -20 dB. The cadence state machine has 3 states, which detect
a single on/off cycle of the busy tone. The first state detects the first rising edge, with no time
parameters. The second state waits for the falling edge, and checks that the signal on time
was between 300 and 450 ms. The third state then waits for the next rising edge, and checks
if its off time was between 300 and 450 ms. If so, then a VPB_AUSTEL_BUSY event is posted to
the API queue. If any of these conditions fail then the state machine resets and no events are
generated.
Example 5. Austel busy tone
static VPB_DETECT toned_austel_busy = {

VPB_AUSTEL_BUSY, // tone id
425, // freq1
100, // bandwidth1
0, // freq2, N/A
0, // bandwidth2:N/A
-20, // level1
0, // level2, N/A
0, // twist:N/A
10, // SNR: 10dB
40, // glitch duration 40ms
VPB_RISING, // state
0
0,
0,
0,
VPB_FALLING, // state 1
0,
300,
450,
0,
300,
450,
};
DTMF tone detection
This example demonstrates the ability of the programmable tone detector to detect tones with
two frequency components, in this case the DTMF tone for 1, composed of 697 Hz, and 1209
Hz. The variable toned_dtmf1 below illustrates the configuration for this tone.
The signal detection parameters are straightforward, both frequencies have the same level
thresholds. The twist parameter specifies the maximum permissible difference in the
magnitudes of the two frequency components of the tones, in this case it is 10 dB. The
cadence state machine looks for a rising edge, then the tone must be present for a minimum
of 100 ms before a VPB_TONEDETECT event with the data member set to DTMF_1 (user
#defined to a unique tone identifier) is posted.
Example 6. DTMF tone detector
static VPB_DETECT toned_dtmf1 = {

DTMF_1, // tone id
697, // f1: centre frequency
100, // bw1: bandwidth
1209, // f2: centre frequency
100, // bw2: bandwidth
-20, // A1: -20 dBm0
-20, // A2: -20 dBm0
10, // twist: 10 dB
10, // SNR: 10 dB
40 // glitch duration 40ms
0,
0,
0,
VPB_TIMER, // state 1
100,
0,
0
};
Example 4 - Grunt Detector used to detect wide band signals such as voice
This discussion refers to the toned_grunt variable below.
Voice signals have a wide band signal characteristic, with most of the energy located between
50-2000Hz. The grunt detector looks for wide band energy between 500Hz and 3500Hz. The
lower frequency band (500Hz) was selected as not to overlap with other telephony signals,
such as dial and busy tones which have their energy centred around 400Hz. The cadence state
machine has 2 states to detect a wideband signal. The first state waits for 1 second, ignoring
any signal transitions. The second state checks for a rising edge in the signal with an off time
between 0-40 ms. If so, then a VPB_GRUNT event is posted to the API queue. If any of these
conditions fail then the state machine resets and no events are generated.
Example 7. DTMF tone detector

static VPB_DETECT toned_grunt = {
VPB_GRUNT, // tone id
2000, // freq1
3000, // bandwidth1
0, // freq2, N/A
0, // bandwidth2: N/A
-40, // level1 (-40 dB)
0, // level2, N/A
0, // twist: N/A
0, // SNR: N/A
40 // glitch duration 40ms
VPB_DELAY, // state 0
1000,
0,
0,
0,
40,
0
};
DTMF and Programmable Tone Automated Tone Training

Generation
<<<
Previous Next >>>
Automated Tone Training

Introduction
To make programming the tone detectors easier, an automated tone training application,
tonetrain, has been developed, and is included in the vpb-driver software.
Using this application, tone training is a three step process:
1. Record a sample of the tone.

2. Run tonetrain to analyse the sample and determine suitable tone detector
parameters.
3. Test the tone detector parameters on your recorded tone

Compiling
First ensure you have already compiled the driver (see README in the root directory of vpb-
driver).
$cd tonetrain
$./configure
$make
Tutorial
Setup
To sample tones you will need a Voicetronix card, for example an OpenLine4 or
OpenSwitch12 card. This card should be installed and tested. You will also need to connect a
port of the Voicetronix card to the telephone line that you wish to train tones for. Different
telephone line and PBXs tend to generate different tones. A second phone line or mobile
(cell) telephone is also useful.
Make sure you have compiled, installed and tested the Voicetronix driver. You will also need
to have compiled recwav and tonedebug, both located in the unittest directory.
Sample files
There are some sample files in the tonetrain sub-directory. They are:
400-c-tone.wav - a continous tone of 400Hz
600-c-tone.wav - a continous tone of 600Hz
hs-dialtone.wav - dial tone from our PBX
hs-ringback.wav - ring back tone from our local exchange
Using these files you can run tonetrainer and then plug the results back into tonedebug (this
requires a Voicetronix board)
Dial Tone Training Example
To record a sample, perform this command from the unittest directory:
$ ./recwav dialtone.wav 1 10
This will record 10 seconds of signal on port 1 or the Voicetronix card. Before recording, recwav
takes the line off hook, which will cause dial tone to be generated by your exchange of PBX. If your
telephone line is connected to a different port, change the second argument.
It is a very good idea to check that the sample file is of good quality, and contains only the
tone to be trained. You can play back the tone using playwav, or using a suitable command
line or GUI utility.
If the sample file is of poor quality, then the automated tone training process will fail. It must
contain just the tone sample to be trained, for example no human speech or other tones.
Now to determine the tone parameters, perform this command:
$ tonetrain/tonetrain -e -w dialtone.wav
The -e option specifies the environment variable output format, the -w WaveFile specifies a wave
file input format.
You should get a result like this:
Environment variable format result:

export VPB_TONE=5,C,421,100,2000
The arguments to the Environment variables are:
export VPB_TONE=<Tone ID>,<Tone Type>,<Tone Frequency1>,<{Type

dependant}...>
Now perform this command to set the environment variable, note that we have changed the
Tone ID from 5 to DIAL:
$ export VPB_TONE=DIAL,C,421,100,2000
This environment variable is read by the vpb driver when it starts. The driver uses this information to
configure the tone detector to recognise the tone you have just trained. For more information on the
tone detector parameters (and how to set them) please see the previous section.
There are several other output formats for tonetrain, see the command line help for more
information.
After training, you can then test the tone detector using tonedebug. First, disconnect your
telephone line from the Voicetronix card. Then:
$ ./tonedebug -e -w dialtone.wav
Using Environment...
Note: -w option used for testing tone detector based
on wave files echoed from tx->rx side of hybrid -
make sure no telephone line connected to port 1!
[00] Record fifo overflow
[00] Tone Detect: Dial
[00] Play End
As with tonetrain, -e specifies the environment variable output format, the -w WaveFile
option specifies wave file input format for the sample used to test the tone detector.
Ringback Tone Example
Ringback is the tone you hear in your telephone handset when the destination phone is
ringing. It starts just after dialling and stops when the destination phone is answered.
To record a sample, you will to have a destination number that will not get answered and is
not busy! Again we will use the recwav application:
$ ./recwav ringback.wav 1 10 --dial ,,555
This example assumes that the destination number you are calling is 555 (just like the movies). The
commas generate a 1 second pause in the dialling, which is useful as some PBXes and exchanges like
pauses before (and during dialling). You should hear the phone at the destination number (in this
case 555) ringing during the record process.
If you don't hear the destination phone ringing, then there may have been a problem dialling.
Investigate and correct this before proceeding.
As with the dial tone example, it is a very good idea to listen to the recorded sample to ensure
it contains the correct ringback tone sample before proceeding with the training stage.
You can then process it through tonetrain and tonedebug as before:
$ tonetrain/tonetrain -e -w ringback.wav

export VPB_TONE=5,P,453,100,1690
$ export VPB_TONE=RINGBACK,P,453,100,1690
$ ./tonedebug -e -w ringback.wav
[00] Tone Detect: Ringback
[00] Play End
Busy Tone Example
To record a sample, you will to have a destination number that will be busy and wont go to
voice mail (you could use the number that you are calling from). Again we will use the
recwav application:
$ ./recwav busy.wav 1 10 --dial ,,555
You can then run it through tonetrain and tonedebug as before:

$ tonetrain/tonetrain -e -w busytone.wav

export VPB_TONE=5,P2,421,100,1000
$ export VPB_TONE=BUSY,P2,421,100,1000
$ ./tonedebug -e -w busytone.wav
[00] Play End
Tone Detection Timers

<<< Next
Previous >>>
Timers
The VPBAPI includes support for programmable timers that operate through the API event
queue. The timers are useful for integrating timer functions into state machine based
computer telephony applications.
The following functions support the API timers:
vpb_timer_open()
vpb_timer_close()
vpb_timer_start()
vpb_timer_stop()
vpb_timer_restart()
vpb_timer_get_unique_timer_id()
vpb_timer_change_period()
Timers have two states, running, and stopped. When a timer is first created with
vpb_timer_open(), the timer is in the stopped state. The timer can be placed in the running
state using vpb_timer_start() or vpb_timer_restart().
When the timer period expires, it posts a VPB_TIMER event and resets itself to the stopped
state. The timer can then be restarted using vpb_timer_start() or vpb_timer_restart()
and the cycle repeated. The timer can be restarted before its period has expired using
vpb_timer_restart(). Timer events are classed as solicited events, they will always be
posted to the event queue and cannot be masked out.

Automated Tone Training WAVE File and AU File
Functions

<<< Next
Previous >>>
WAVE File and AU File Functions

The following functions allow the user to manipulate WAVE and AU files through the VPBAPI:
vpb_wave_open_write()
vpb_wave_write()
vpb_wave_close_write()
vpb_wave_open_read()
vpb_wave_read()
vpb_wave_close_read()
vpb_wave_set_sample_rate()
vpb_wave_seek()
vpb_wave_get_mode()
When writing to a wave file the user must initially open up a wave file using
vpb_wave_open_write() to set up the appropriate wave format and filename. Writing to the
file is then handled by vpb_wave_write(). The wave file must be closed by the
vpb_wave_close_write().
Reading a wave file requires a similar procedure, initially opening up the wave file using
vpb_wave_open_read() to determine the file's wave format. Reading the file is then handled
by vpb_wave_read(). The wave file must be closed by the vpb_wave_close_read().
The vpb_wave_get_mode() obtains the compression format of a wave file. This function is
useful in instances where the user-define play routines are required. The vpb_wave_seek()
moves the file pointer of the wave file to a specified location.

Timers Get Digits Functions

<<<
Previous Next >>>
Get Digits Functions

The VPBAPI supports the collection of digits from a channel. This includes an asynchronous
and synchronous version. The functions initiate collection of the digits from the channel and
place them in a user digit buffer:
vpb_get_digits_sync()
vpb_get_digits_async()
The conditions of termination for the functions may be configured via the VPB_DIGITS
structure. In the asynchronous version, the condition of termination is passed to the data field
of the VPB_EVENT structure once the collection of digits from the channel to the user digit
buffer has terminated.
The synchronous version returns the appropriate termination code (see vpbapi.h) once the
function has ended. A flush function is also included to reset the user digit buffer.
vpb_flush_digits() Ensure this is used to clear the user digit buffer of any digits from
previous actions on the channel before executing any of the get digits functions.
Get Digit Termination codes

Termination code Description
VPB_DIGIT_TERM Termination due to a user-defined termination-digit being

pressed
VPB_DIGIT_MAX Termination due to having reached the maximum number of

digits
VPB_DIGIT_TIME_OUT Termination due to the time limit to collect digits having

expired
VPB_DIGIT_INTER_DIGIT_TIME_OUT Termination due to the inter-digit time limit having expired
WAVE File and AU File Functions Call Progress Functions

<<<
Previous Next >>>
Call Progress Functions

The VPBAPI enables a call to be placed using the call progress algorithm in both
synchronous and asynchronous modes. It also enables the call progress parameters to be set
or obtained for each channel.
vpb_get_call()
vpb_set_call()
vpb_call_sync()
vpb_call_async()
Call progress analysis determines whether a call is answered or not, whether the line is busy,
or there are problems placing the call such as no dial tone, call disconnected or no ring back.
The call progress algorithm consists of frequency and cadence analysis to determine the state
of the call being placed.
The VPB_CALL and VPB_TONE_MAP structures are used to define the parameters of the call
progress algorithm. In the asynchronous version, the status of the call is passed to the data
field of the VPB_EVENT structure. The synchronous version returns the appropriate call
progress return code (see vpbapi.h) once the function has ended.
Call Progress Return codes

Return code Description
VPB_CALL_CONNECTED Call is connected
VPB_CALL_NO_DIAL_TONE No dial tone is detected
VPB_CALL_NO_RING_BACK No ring back is detected
VPB_CALL_BUSY Call is busy
VPB_CALL_NO_ANSWER No answer is detected
VPB_CALL_DISCONNECTED Call is disconnected

Return code Description
Get Digits Functions VOX Functions

<<< Next
Previous >>>
VOX Functions
The VPBAPI allows the user to control the VOX firmware for each channel.
vpb_getvox()
vpb_setvox()
The VOX algorithm switches on when the audio level exceeds onlevel. When the audio level
falls beneath offlevel, a counter is started. When the counter exceeds runon milliseconds, the
VOX algorithm switches off. The overload level is defined as 0 dB, the default on and off
VOX levels are -12 and -18 dB respectively. The default runon duration is 2000 ms. The
VOX parameters may be re-programmed using the vpb_setvox() function.

Call Progress Functions Pip Functions

<<< Next
Previous >>>
Pip Functions
The following functions support pip generation on the OpenLog8i:
vpb_get_pip()
vpb_set_pip()
vpb_pip_on()
vpb_pip_off()
There is a requirement by national communication authorities, in the instance of recording
calls, that the parties must be notified that their call is being recorded. The pip parameters, the
length of the pip pulse and the period between pulses, can be modified by vpb_set_pip().
The VPB_PIP structure contains these parameters.

VOX Functions Miscellaneous Functions

<<< Next
Previous >>>
vpb_get_model()
vpb_sleep()
vpb_sethook_sync()
vpb_sethook_async()
vpb_translate_event()
vpb_open()
vpb_close()
vpb_seterrormode()

Pip Functions Function Reference
<<<
Previous
Function Reference
vpb_config()
Synopsis
int WINAPI vpb_config(int num_cards, int *bases, char *firmware_file, int

model) {
Function
Set installation specific config info, call before vpb_open(). If this function is called, it
overrides any other settings (for example compile-time defaults or env vars).
vpb_set_call()
Synopsis
int WINAPI vpb_set_call(int handle, VPB_CALL *vpb_call)
Function
Function to set call progress parameters.
vpb_get_call()
Synopsis
int WINAPI vpb_get_call(int handle, VPB_CALL *vpb_call)
Function
Function to get current call progress parameters.
vpb_call_sync()
Synopsis
int WINAPI vpb_call_sync(int handle, char *dialstr)
Function
Place a call using call progress algorithm. Note: when this function is called, make sure dial
tone has not been detected yet.
vpb_call_async()
Synopsis
int WINAPI vpb_call_async(int handle, char *dialstr)
Function
Place a call using call progress algorithm, async version. Note: when this function is called,
make sure dial tone has not been detected yet.
vpb_cid_debug_on()
Synopsis
void WINAPI vpb_cid_debug_on(char debug_file_name[]) {
Function
Call this function to enable debugging of the CID module. Causes lots of debug info to be
written to the text file "debug_file_name".
vpb_cid_decode()
Synopsis
int WINAPI vpb_cid_decode(

char *number,
short *in,
int n
)
Function
As per cid-demodulate() but parse out all CID fields.
vpb_cid_demodulate()
Synopsis
int WINAPI vpb_cid_demodulate(char* number, int* nChars, short* in, int n)
Function
Attempts to decode CID information from an array of samples. Throws various exceptions
should an error occur. Returns the caller number in "number". Will return a null-str in
"number" if no caller number supplied.
vpb_start()
Synopsis
int WINAPI vpb_start(int num_cards, int *bases, char *firmware_file, int

model)
Function
Initialises the API software (boots DSPs etc) when operating in "bayonne" mode. Calling this
function before vpb_open() starts the driver in "bayonne" mode. If vpb_open() is called
without calling this function first, the driver is started in "regular" mode. The major feature of
bayonne mode is that the user must set up a thread to periodically call (poll) the
vpb_get_event_async_bayonne() function. Without this thread the driver will not function.
This has certain advantages where the user whishes to control the number of threads in the
system, and was specifically written for the bayonne package (www.bayonne.cx). See the
unittest tvpb.cpp for an example of a program implemented using bayonne mode. In regular
mode, the driver sets up all sorts of polling threads which leads to generally simpler
application code. In other words the choice of bayonne vs regular mode is the usual choice of
flexibility vs complexity :-). Most of the programs in the unittest directory use regular mode.
Note: bayonne mode was originally supported by the 2.0.x series vpb drivers, and regular
mode by the 1.x.y series of drivers.
vpb_open()
Synopsis
int WINAPI vpb_open(unsigned int board, unsigned int channel)
Function
Opens a VPB device (channel), and returns a handle to that device. See also vpb_start().
vpb_close()
Synopsis
int WINAPI vpb_close(int devhandle)
Function
Closes a device. If this is the last device remaining, then the API is closed down (memory
free-ed, DSP stopped etc).
vpb_stop()
Synopsis
int WINAPI vpb_stop()
Function
API is closed down (memory free-ed, DSP stopped etc). Only used for "bayonne" mode.
vpb_get_event_async_bayonne ()
Synopsis
int WINAPI vpb_get_event_async_bayonne(

int board, // VPB board number: 1,2,3..
VPB_EVENT *ev // event
)
Function
Note: This function is only used in "bayonne" mode. Please do not call in "regular" mode -
see also vpb_start() This function returns an event from the specified VPB card. If an event is
available it returns VPB_OK, otherwise it returns VPB_NO_EVENTS. When this function
returns, it should be called again as soon as possible in a tight polling loop, as it is responsible
for sequencing several time-sensitive operations (e.g. playing DTMF tones). Avoid placing
blocking functions in the polling loop that calls this function, to ensure it is called regularly.
Once every 20ms is recommended. IMPORTANT: This function must be called regularly, as
the driver uses this function to service time critical tasks in the driver. This function must be
polled regularly, even if no events are required for the program. Without it, other functions,
such as play/record, will not work.
vpb_set_event_callback()
Synopsis
int WINAPI vpb_set_event_callback(int handle, void (WINAPI *event_callback)

(VPB_EVENT *e, void *context), void *context)
Function
Sets the event callback function for each channel. By default no event callback functions are
set, in this case events are posted to the API event Q. If this function has been called with a
non-null function pointer, the event callback funcion is called with the event as an argument
rather than posting the event to the API Q. The user defined event callback function should be
of the form: void event_callback(VPB_EVENT *e); To disable the event callback, call this
function with a NULL pointer for the function argument.
vpb_set_event_mask()
Synopsis
int WINAPI vpb_set_event_mask(int handle, unsigned short mask)
Function
Function to set the event mask for each device. Each call to this function overwrites the
previous event mask.
vpb_get_event_mask()
Synopsis
int WINAPI vpb_get_event_mask(int handle)
Function
Function to return the current event mask for a given device.

vpb_enable_event()
Synopsis
int WINAPI vpb_enable_event(int handle, unsigned short mask)
Function
Function to unmask (enable) only the specified events while leaving the rest of the event
masks unchanged.
vpb_disable_event()
Synopsis
int WINAPI vpb_disable_event(int handle, unsigned short mask)
Function
Function to mask out (disable) specified events only, while leaving the rest of the event
masks unchanged.
vpb_put_event()
Synopsis
int WINAPI vpb_put_event(VPB_EVENT *e)
Function
Function to place an event on the API event queue exported API version.
vpb_get_event_async()
Synopsis
int WINAPI vpb_get_event_async(VPB_EVENT *e)
Function
Function to get an event from the API event queue. Returns VPB_OK if an event available,
other wise VPB_NO_EVENTS if Q empty.
vpb_get_event_sync()
Synopsis
int WINAPI vpb_get_event_sync(VPB_EVENT *e, unsigned int time_out)
Function
This function waits until an event is available on the API Q, then returns. The thread is put to
sleep until the event becomes available. Function returns VPB_OK if event returned, else
VPB_TIME_OUT if sync function times out. Use tme_out = 0 for no timeout.
vpb_get_event_ch_sync()
Synopsis
int WINAPI vpb_get_event_ch_sync(int h, VPB_EVENT *e, unsigned int

time_out)
Function
This function waits until an event is available on the API Q, then returns. The thread is put to
sleep until the event becomes available. This version only returns events from a specified
channel.
vpb_get_event_ch_async()
Synopsis
int WINAPI vpb_get_event_ch_async(int h, VPB_EVENT *e)
Function
This reads an event on a channels event queue if available.
vpb_sethook_async()
Synopsis
int WINAPI vpb_sethook_async(int chdev, int hookstate)
Function
Function to set the hook status of a particular chnnel device. This version returns
immediately.
vpb_sethook_sync()
Synopsis
int WINAPI vpb_sethook_sync(int chdev, int hookstate)
Function
Function to set the hook status of a particular chnnel device. This version returns after the
hook status has been changed.
vpb_set_station_sync()
Synopsis
int WINAPI vpb_set_station_sync(int chdev, int state)
Function
Function to set the status (on or off) of a station port channel device. This version returns
after the status has been changed. NOTE: DR 22/8/02 - this function is not normally required,
as hook detector logic has been modified to automatically turn off/on station audio with hook
switch.
vpb_ring_station_async()
Synopsis
int WINAPI vpb_ring_station_async(int chdev, int state)
Function
Function to start/stop a station port ringing. This version rings stations with a pre-defined
cadence.
vpb_ring_station_sync()
Synopsis
int WINAPI vpb_ring_station_sync(int chdev, int state)
Function
Function to start/stop a station port ringing.
vpb_user_ring_station_sync()
Synopsis
int WINAPI vpb_user_ring_station_sync(int chdev, int state)
Function
Function to start/stop a station port ringing. This version allows the caller (user) to define the
cadence. Station will ring continuously when called with state==1, until called with state==0.
Care should be taken to ring no more than that 4 stations at any one time, to prevent
overloading the OpenSwitch12 ring generator. Excess load of the ring generator will not
result in permanent damage, however the station power supply to shut down, requiring a
power down of the OpenSwitch12 (ie switching the PC off) to reset. This function should not
be used in conjunction with vpb_ring_station_sync, the cadenced ring generator function, as
the driver will get confused!
vpb_sleep()
Synopsis
void WINAPI vpb_sleep(long time)
Function
Function to put the current thread to sleep for a certain time in ms. Used during testing to
reduce the amount of time program spends in main polling loop so that the computational
load of the timer callback can be measured.
vpb_adpcm_open()
Synopsis
int WINAPI vpb_adpcm_open(void **pv)
Function
Sets up the state variables for ADPCM opertaions. Must be called before any other ADPCM
functions.
vpb_adpcm_close()
Synopsis
void WINAPI vpb_adpcm_close(void *pv)
Function
Closes down the ADPCM state variables, freeing memory. Call after all ADPCM operations
have finished.
vpb_adpcm_reset()
Synopsis
void WINAPI vpb_adpcm_reset(void *pv)
Function
Resets the ADPCM state variables.
vpb_adpcm_decode()
Synopsis
int WINAPI vpb_adpcm_decode(

void *pv, // ADPCM state variables
short linear[], // linear output samples
unsigned short *size_lin, // number of 16 bit samples out
char adpcm[], // packed ADPCM samples
unsigned short size_adpcm // number of bytes in (must be
even)
Function
Converts a buffer of compressed OKI ADPCM samples to a buffer of 16 bit linear samples.
vpb_adpcm_encode()
Synopsis
int WINAPI vpb_adpcm_encode(

void *pv, // ADPCM state variables
char adpcm[], // output packed ADPCM samples
unsigned short *size_adpcm, // number of bytes out
short linear[], // linear input samples
unsigned short size_linear // number of 16 bit samples in
)
Function
Converts a buffer of 16 bit linear samples to a buffer of compressed OKI ADPCM samples.
vpb_comp_load()
Synopsis
int WINAPI vpb_comp_load(unsigned short board)
Function
Interrogates the DSP to determine the computational loading. Causes a comp load statement
to be printed if mprintf's are enabled. Dont expose the function to the punters, keep it as
undocumented for our use only.
vpb_echo_canc_force_adapt_on()
Synopsis
int WINAPI vpb_echo_canc_force_adapt_on()
Function
Forces the echo cancellers to adapt all of the time, ie switches off near end speech detector.
Used to determine maximum computational load.
vpb_echo_canc_force_adapt_off()
Synopsis
int WINAPI vpb_echo_canc_force_adapt_off()
Function
Stops forced adaptation.
vpb_echo_canc_enable()
Synopsis
int WINAPI vpb_echo_canc_enable()
Function
Enables the echo cancellers.
vpb_echo_canc_disable()
Synopsis
int WINAPI vpb_echo_canc_disable()
Function
Disables the echo cancellers, but keeps adaptation on.
vpb_echo_canc_get_sup_thresh()
Synopsis
int WINAPI vpb_echo_canc_get_sup_thresh(short *thresh)
Function
Gets the current echo suppressor threshold. This threshold is the same for all channels on all
cards.
vpb_echo_canc_set_sup_thresh()
Synopsis
int WINAPI vpb_echo_canc_set_sup_thresh(short *thresh)
Function
Sets the current echo suppressor threshold. This threshold is the same for all channels on all
cards. 0x1000 (4096) -18dB 0x800 (2048) -24dB 0 0 no supressor
vpb_get_model()
Synopsis
int WINAPI vpb_get_model(char *s) {
Function
Returns a string containing the VPB model, driver should be started first by at least one call
to vpb_open().
vpb_get_ports_per_card()
Synopsis
int WINAPI vpb_get_ports_per_card() {
Function
Returns the number of ports on each card.
vpb_set_codec_reg()
Synopsis
void WINAPI vpb_set_codec_reg(int chdev, // channel handle

USHORT addr, // 8-bit address of codec
register
USHORT data // 8-bit data to write to
register
)
Function
Used to set a register of the TS5070 codecs, allows driver-level config of codec, rather than
hard-coding in DSP firmware.
vpb_get_num_cards()
Synopsis
int WINAPI vpb_get_num_cards()
Function
Returns the number of cards in the system. In current implemention need to call vpb_open()
or vpb_start() before calling this function. This means e.g. one channel should be opened
before determining how many cards there are! This is very silly and should be fixed some
time!
vpb_bridge()
Synopsis
int WINAPI vpb_bridge(

int h1, // handle of first channel
int h2, // handle of second channel
int mode, // VPB_BRIDGE_ON | VPB_BRIDGE_OFF
int resource // bridge resource 1 or 2 (V4PCI only)
Function
Bridges two ports using the driver, to allow 2-way conferencing. The bridging is
implemented at a low level (firmware and/or hardware) by the driver to ensure a low delay
connection between the ports. Note that only ports on the same physical card can be bridged
using this method on the V4PCI and ISA boards. Two bridging resources are available on the
V4PCI (1 & 2). V4PCI: For 3 or more way conferencing (or bridging between ports on
different cards) use "software bridging" using the play and record buf API functions. This
results in a higher delay (20ms or so), however this does not cause a problem due to the echo
canceller on each VPB port. OpenSwitch: This will auto-magically switch to a kernel-mode
driver version of bridging when bridging across boards. For more information on this look at
the vpb_listen function.
vpb_listen()
Synopsis
int WINAPI vpb_listen(

int h1, // handle of first channel
int h2, // handle of second channel
int mode // VPB_BRIDGE_ON | VPB_BRIDGE_OFF
)
Function
Software bridge/listen for OpenSwitch boards. Starts a half duplex bridge between two
handles. For a full duplex bridge, both handles will need to listen between each other. This
currently only works on OpenSwitch boards.
vpb_conf()
Synopsis
int WINAPI vpb_conf(

int h, // Handle of channel/port
int resource, // Conference/party resource to use (0-9)
Function
Multi party conferencing. Can be used across any number of OpenSwitch boards. There is a
maximum of 10 conferences with a max of 10 people each. You may need to reduce the HW-
record gain if you experiance excesive feed back.
vpb_watchdog_enable()
Synopsis
int WINAPI vpb_watchdog_enable(int h, int enable) {
Function
Enables (enable == 1), or disables (enable == 0) V12PCI watchdog timer. There is one
watchdog timer per board, so only one call per board is required, any handle h from that
board can be used. Once enabled, it must be reset at least once every 8 seconds by
vpb_watchdog_reset. If it is not reset the watchdog timer will fire. Once fired, the hardware
will assume the PC has crashed, and the first 4 station ports will be connected to the first 4
loop ports to preserve basic phone functionality. Use of the watchdog timer assumes a mixed
station/loop configuration. Do not use the watchdog timer when the card is configured as all
loop or all station cards.
vpb_watchdog_reset()
Synopsis
int WINAPI vpb_watchdog_reset(int h) {
Function
Resets watchdog timer. Call at least once every 8 seconds to prevent watchdog timer firing.
Does nothing when watchdog timer is disabled. There is one watchdog timer per board, so
only one call per board is required, any handle h from that board can be used.
vpb_get_card_info()
Synopsis
int WINAPI vpb_get_card_info(

int board, // Board number
VPB_CARD_INFO *detail // Card Info Structure to
fill.
)
Function
Returns the card details in a structure VPB_CARD_INFO. Includes: Model name, Serial
number, Revision number, Manufacture Date All strings are null terminated. Note: Only
supported under Linux at this time!
vpb_get_digits_async()
Synopsis
int WINAPI vpb_get_digits_async(int handle, VPB_DIGITS *newdig, char *buf)

Function
Gets a buffer of digits based on the conditions passed to the function. Returns immediately,
and posts a comletetion event when the buffer has been obtained. If this function is called
while already collecting digits (by a prvious call to this function), the digit collection is reset,
and digits collected so far are discarded.
vpb_get_digits_sync()
Synopsis
int WINAPI vpb_get_digits_sync(int handle, VPB_DIGITS *newdig, char *buf)
Function
Gets a buffer of digits based on the conditions passed to the function. Returns when digit
buffer has been obtained, with appropriate VPB_DIGIT_XXX return code.
vpb_flush_digits()
Synopsis
int WINAPI vpb_flush_digits(int handle)
Function
Clears the internal digit buffer, often called before vpb_get_digits_xxxx.
vpb_wave_open_write()
Synopsis
int WINAPI vpb_wave_open_write(void **ppv, char filename[], int mode)
Function
Opens a RIFF Wave file.
vpb_wave_open_read()
Synopsis
int WINAPI vpb_wave_open_read(void **ppv, char filename[])
Function
Opens a RIFF Wave file for reading.

vpb_wave_close_write()
Synopsis
void WINAPI vpb_wave_close_write(void *wv)
Function
Closes a RIFF Wave file after writing.
vpb_wave_close_read()
Synopsis
void WINAPI vpb_wave_close_read(void *wv)
Function
Closes a RIFF Wave file after reading.
vpb_wave_write()
Synopsis
int WINAPI vpb_wave_write(void *wv, char buf[], long n)
Function
Writes a block of speech samples to a RIFF Wave file.
vpb_wave_read()
Synopsis
int WINAPI vpb_wave_read(void *wv, char buf[], long n)
Function
Reads a block of speech samples from a RIFF Wave file. Returns the number of bytes read.
vpb_wave_seek()
Synopsis
int WINAPI vpb_wave_seek(void *wv, long offset)
Function
Moves wave pointer to a specified location in samples, with respect to the beginning of the
file.
vpb_wave_set_sample_rate()
Synopsis
void WINAPI vpb_wave_set_sample_rate(void *wv, unsigned short rate)
Function
Changes the sample rate of a wave file.
vpb_wave_get_mode()
Synopsis
int WINAPI vpb_wave_get_mode(void *wv, unsigned short *mode)
Function
Determines the compression mode of a wave file.
vpb_setagc()
Synopsis
int WINAPI vpb_setagc(int handle, VPB_AGC *agc)
Function
Sets the agc parameters for a specified channel.
vpb_getagc()
Synopsis
int WINAPI vpb_getagc(int handle, VPB_AGC *agc)
Function
Gets the agc parameters for a specified channel.
vpb_play_set()
Synopsis
int WINAPI vpb_play_set(int handle, VPB_PLAY *vpb_play)
Function
Sets play parameters or this channel.

Synopsis
int WINAPI vpb_play_buf_start(int handle, unsigned short mode)
Function
API callable version of play_buf_start.
vpb_play_buf_sync()
Synopsis
int WINAPI vpb_play_buf_sync(int handle, char *buf, unsigned short length)
Function
API version of play_buf_sync(). Returns VPB_FINISH if playing should finish, else returns
VPB_OK.
Synopsis
int WINAPI vpb_play_buf_finish(int handle)
Function
Completes the playing of a channel.
Synopsis
int WINAPI vpb_play_file_sync(int handle, char file_name[])
Function
Utility function to play a file to a channel. Function returns when playing is finished.
Synopsis
int WINAPI vpb_play_voxfile_sync(int handle, char file_name[],

unsigned short mode)
Function
Function to play a vox file to a channel. Function returns when playing is finished.
Synopsis
int WINAPI vpb_play_file_async(int handle, char file_name[], int data)
Function
Utility function to play a file to a channel. Function returns as soon as playing has started,
and places an event on the API Q when playing has finished.
Synopsis
int WINAPI vpb_play_voxfile_async(int handle, char file_name[],

unsigned short mode,int data)
Function
Utility function to play a vox file to a channel. Function returns as soon as playing has
started, and places an event on the API Q when playing has finished.
vpb_play_terminate()
Synopsis
int WINAPI vpb_play_terminate(int handle)
Function
Stops playing immediately. Does nothing if we are not playing. NOTE: this doesnt have to be
in the same thread context as vpb_play_buf_xxxx
vpb_record_set()
Synopsis
int WINAPI vpb_record_set(int handle, VPB_RECORD *vpb_record)
Function
Sets record parameters or this channel.
Synopsis
int WINAPI vpb_record_buf_start(int handle, unsigned short mode)
Function
API callable version of record_buf_start. NOTE: All vpb_record_buf_xxxx functions for a
given channel must be executed in the same thread context.
Synopsis
int WINAPI vpb_record_buf_sync(int handle, char *buf, unsigned short

length)
Function
API version of record_buf_sync(). NOTE: All vpb_record_buf_xxxx functions for a given

channel must be executed in the same thread context.
Synopsis
int WINAPI vpb_record_buf_finish(int handle)
Function
Completes the recording of a channel. NOTE: All vpb_record_buf_xxxx functions for a given
channel must be executed in the same thread context.
Synopsis
int WINAPI vpb_record_file_sync(int handle, char file_name[], unsigned

short mode)
Function
Utility function to record a file to a channel. Function returns when recording is finished.
Synopsis
int WINAPI vpb_record_voxfile_sync(int handle, char file_name[], unsigned

short mode)
Function
Utility function to record a vox file to a channel. Function returns when recording is finished.
Synopsis
int WINAPI vpb_record_file_async(int handle, char file_name[],
Function
Utility function to record a file from a channel. Function returns as soon as recording has
started, and places an event on the API Q when recording has finished.
Synopsis
int WINAPI vpb_record_voxfile_async(int handle, char file_name[],

Function
Utility function to record a vox file from a channel. Function returns as soon as recording has
started, and places an event on the API Q when recording has finished.
vpb_record_terminate()
Synopsis
int WINAPI vpb_record_terminate(int handle)
Function
Stops recording immediately. Does nothing if we are not recording. NOTE: this doesnt have
to be in the same thread context as vpb_record_buf_xxxx
vpb_play_set_gain()
Synopsis
int WINAPI vpb_play_set_gain(int handle, float gain)
Function
Sets the gain of the play channel, using the hardware gain of the TS5070 codec on the VPB4.
JK: 9/4/02 Modified to only set software gain and not the hardware gain of the TS5050
codec.
vpb_play_set_hw_gain()
Synopsis
int WINAPI vpb_play_set_hw_gain(int handle, float gain)
Function
Externally accessible wrapper around play_set_hw_gain.
vpb_play_get_gain()
Synopsis
int WINAPI vpb_play_get_gain(int handle, float *gain)
Function
Gets the total gain of the play channel. It comprising of a softare and hardware component
(TS5070 codec) on the VPB4/V4PCI.
vpb_record_get_gain()
Synopsis
int WINAPI vpb_record_get_gain(int handle, float *gain)
Function
Gets the total gain of the play channel. It comprising of a softare and hardware component
(TS5070 codec) on the VPB4/V4PCI.
vpb_record_set_gain()
Synopsis
int WINAPI vpb_record_set_gain(int handle, float gain)
Function
Sets the total gain of the record channel. The total gain is comprised of a software and
hardware component (TS5070 codec). Previously it only comprised of the hardware
component. JK 9/4/02 Modified to only set sofware record gain. Disabled hardware
configured record gain.
vpb_record_set_hw_gain()
Synopsis
int WINAPI vpb_record_set_hw_gain(int handle, float gain)
Function
Externally accessible wrapper around record_set_hw_gain.
vpb_reset_record_fifo_alarm()
Synopsis
int WINAPI vpb_reset_record_fifo_alarm(int handle)
Function
Resets the latch that detects record DSP buffer overflows. After calling this function another
event may be generated if the buffer overflows.
vpb_reset_play_fifo_alarm()
Synopsis
int WINAPI vpb_reset_play_fifo_alarm(int handle)
Function
Resets the latch that detects record DSP buffer underflows. After calling this function another
event may be generated if the buffer underflows.
vpb_settonedet()
Synopsis
int WINAPI vpb_settonedet(int chdev, VPB_DETECT *d)
Function
Enables user to set a user programmed tone, or replace an exisiting tone. Performs translation
of user parameters to VPB message. The tones are defined on a per channel basis. This
version (for the API), stops the config mamanger before download- ing a tone to prevent
computational overoad probs.
vpb_gettonedet()
Synopsis
int WINAPI vpb_gettonedet(int chdev, int id, VPB_DETECT *d)
Function
Enables user to extract a tone detectors parameters.
vpb_debug_tonedet()
Synopsis
int WINAPI vpb_debug_tonedet(int chdev, int id, char file_name[], int sec)
Function
Instructs API to produce a debug file of tone detector parameters for one channel.
vpb_dial_async()
Synopsis
int WINAPI vpb_dial_async(

int chdev, // handle
char *dialstring // string to dial
)
Function
Sends a DTMF string down a channel device, accepts the following characters by default,
plus user defined chars if defined: 0 1 2 3 4 5 6 7 8 9 0 * # A B C D and: & (hook flash) ,
(pause)
vpb_dial_sync()
Synopsis
int WINAPI vpb_dial_sync(

int chdev, // handle
char *dialstring // string to dial
)
Function
Sends a DTMF string down a channel device, accepts the following characters by default,
plus user defined chars if defined: 0 1 2 3 4 5 6 7 8 9 0 * # A B C D and: & (hook flash) ,
(pause)
vpb_settone()
Synopsis
int WINAPI vpb_settone(

char ident, // single char that identifies tone
VPB_TONE *t // structure containing tone parameters
)
Function
Enables user to set a user programmed tone, or replace an existing tone. Performs translation
of user parameters to VPB message.
vpb_gettone()
Synopsis
int WINAPI vpb_gettone(

char ident, // single char that identifies tone
VPB_TONE *t // structure containing tone parameters
)
Function
Enables user to retrieve the parameters of a tone. Performs translation of user parameters
from VPB message.
vpb_playtone_async()
Synopsis
int WINAPI vpb_playtone_async(int handle, VPB_TONE *vpb_tone)
Function
Plays a user defined tone immediately, API version.
vpb_playtone_sync()
Synopsis
int WINAPI vpb_playtone_sync(int handle, VPB_TONE *vpb_tone)
Function
Plays a user defined tone immediately, API version.
vpb_tone_terminate()
Synopsis
int WINAPI vpb_tone_terminate(int handle)
Function
Terminates playing of tones (programmable or DTMFs).
vpb_strerror()
Synopsis
char * WINAPI vpb_strerror(int code)
Function
Converts a numeric error code to a human-readable error description. Passes back a pointer to
a string which describes the error code.
vpb_setvox()
Synopsis
int WINAPI vpb_setvox(int handle, VPB_VOX *vox)
Function
Sets the vox parameters for a specified channel.
vpb_getvox()
Synopsis
int WINAPI vpb_getvox(int handle, VPB_VOX *vox)
Function
Gets the vox parameters for a specified channel.
vpb_cid_set()
Synopsis
int WINAPI vpb_cid_set(VPB_CID *cid_struct, int type, void *value)
Function
VPBAPI function to load valid data of 'type' and 'value' into the passed CID structure.
Loading some fields will set associated fields to NULL automaticly as the fiedls are exclusive
Return: Error if invalid type of value out of range, else OK
vpb_cid_compose_dlp ()
Synopsis
int WINAPI vpb_cid_compose_dlp(VPB_CID *MESG, char *dlp)
Function
Build the message dlp from the VPB_CID structure.
vpb_cid_compose_wav ()
Synopsis
int WINAPI vpb_cid_compose_wav(char *DLP, int DLP_LEN, short *BUFF_WAV,

int *BUFF_PTR)
Function
Encodes the Data Link Packet recived into a CP-FSK wave including CSS & MSS bit
headers. Returns *BUFF_WAV containing *BUFF_PTR samples.
vpb_set_pip()
Synopsis
int WINAPI vpb_set_pip(VPB_PIP *vpb_pip)
Function
Sets the pip parameters for all channels.
vpb_set_pip_ch()
Synopsis
int WINAPI vpb_set_pip_ch(int handle, VPB_PIP *vpb_pip)
Function
Sets the pip parameters for a specifed channel.
vpb_get_pip()
Synopsis
int WINAPI vpb_get_pip(VPB_PIP *vpb_pip)
Function
Gets the pip parameters for the first channel.
vpb_get_pip_ch()
Synopsis
int WINAPI vpb_get_pip_ch(int handle, VPB_PIP *vpb_pip)
Function
Gets the pip parameters for the specified channel.
vpb_pip_on()
Synopsis
int WINAPI vpb_pip_on(int handle)
Function
Enables pip generation for a channel.

vpb_pip_off()
Synopsis
int WINAPI vpb_pip_off(int handle)
Function
Disables pip generation for a channel.
vpb_seterrormode()
Synopsis
int WINAPI vpb_seterrormode(

int mode
)
Function
Helper function that determines the way errors are handled in the RunTimeError function
below. See RunTimeError() for more info.
vpb_throw_exception()
Synopsis
void WINAPI vpb_throw_exception(int c, char trans[], char api_function[])
Function
Helper function that throws a VpbException.
vpb_timer_open()
Synopsis
int WINAPI vpb_timer_open

(
void **ppv, // ptr to timer state variables
int chdev, // channel device handle
int timer_id, // Optional ID for this timer
unsigned long period // period in ms before posting event
)
Function
Initialises a timer object for the specified channel device.
vpb_timer_close()
Synopsis
int WINAPI vpb_timer_close
(
void *timer // ptr to timer state variables
)
Function
Deletes a timer object.
vpb_timer_start()
Synopsis
int WINAPI vpb_timer_start

(
void *pv // ptr to timer state variables
)
Function
Starts a timer. When the period specified in vpb_timer_open expires, and event for this
channel device is generated. If timer is already active, this function throws a wobbly.
vpb_timer_restart()
Synopsis
int WINAPI vpb_timer_restart

(
)
Function
ReStarts an already active timer.
vpb_timer_stop()
Synopsis
int WINAPI vpb_timer_stop

(
)
Function
Stops an active timer by removing it from the active list. This function allows the timer to be
stopped from the API.
vpb_timer_change_period()
Synopsis
int WINAPI vpb_timer_change_period

(
void *pv, // ptr to timer state variables
unsigned long newperiod // period in ms before posting event
)
Function
Changes the time out value of a timer that has already been initialised.
vpb_timer_get_unique_timer_id()
Synopsis
int WINAPI vpb_timer_get_unique_timer_id() {
Function
Allows the timer module to generate unique IDs for all of the VPB timer objects in the
system.
vpb_translate_event()
Synopsis
void WINAPI vpb_translate_event(VPB_EVENT *e, char s[])
Function
Function to translate the current event into a string.
<<< Previous Home

Voicetronix Programming Guide

Uploaded by

Copyright:

Available Formats

Voicetronix Programming Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Voicetronix Programming Guide

Uploaded by

Copyright:

Available Formats

Voicetronix Programming Guide