LINETOOLS - Telephone line test tools
-------------------------------------
These programs make use of a PC Sound Card, and some very simple external
hardware to interface your PC to a telephone line. Although primarily
designed as telephony test tools, the programs are also useful for other
non-telephone related audio diagnostics.

The schematic for the testset interface is located in the MICROCAD format
drawing file: LINETOOL.DWG
It should be fairly self explainitory. Note that the line interface
transformer is not specified. I built my interface using a transformer from
my junk box, which originally came from a modem. Many devices which connect
to the phone line will have suitable transformers you can recycle.

-- Sound Card Notes --

LINETOOLS uses a stereo sound card as two independant mono. amplifiers. The
LEFT channel is used to "listen to" audio on the phone line, as well as to
drive the speaker output for audible line monitoring. The RIGHT channel is
used to drive audio onto the line. LINETOOLS accomplishes this by using the
sound cards internal mixer to control the level and routing of the various
audio paths. For this reason, a card with a STEREO mixer is required.
LINETOOLS has been verified to work correctly with Sound-Blaster Pro and 16
series cards. You may me able to use simpler cards if you forgo the speaker,
and use the sound card only for the line interface.

The sound interface uses Creative Labs SOUND BLASTER cards, and the
CT-VOICE.DRV software device driver (included with all DOS versions of the
SOUND BLASTER).

The sound card must be installed and configured according to the manufacturers
instructions, including:

	- SOUND environment variable set to Sound Card directory.
	- CT-VOICE.DRV located in DRV subdirectory of above.
	- BLASTER environment variable set with card settings.
	- Low level drivers loaded (if necessary).

This has been tested and verified to work correctly with SOUND BLASTER 1.5,
2.0, SBPRO and SB16 cards. Older versions of these cards require only the
CT-VOICE.DRV file to be located in a \DRV subdirectory under the "home"
directory indicated by the SOUND environment variable. Later versions of the
cards may also require "Low level" device drivers (CTSB, CTSB2, CTSBPRO or
CTSB16.SYS and CTMMSYS.SYS) to be loaded in your CONFIG.SYS files. Consult
your sound card documentation for details on installing and configuring your
particular card.

If the BLASTER environment variable exists (See sound card installation docs),
LINETOOLS will attempt to reconfigure to the Card type, Address, interrupt and
DMA channel to the parameters indicated, otherwise the default settings
configured in the driver will be used. (see INST-DRV/INSTDRV program supplied
with some cards). Note LINETOOLS uses 'Tn' setting from BLASTER to determine
the type of MIXER on the card.

As manufacturers embrace new graphical operatings systems and industry trends,
they have tended to drop support for the older DOS environment on which
LINETOOLS relies. The CT-VOICE driver used by LINETOOLS is (or were at one
time) standard features included with SOUND BLASTER cards. Later versions of
the cards no longer include these drivers.

If you do not already have a sound card driver, you can use the SBDRV utility
from the CAM package to generate the CT-VOICE.DRV file for SoundBlaster 1.x,
2.x, PRO and 16 series cards. Also, to simplify the installation if LINETOOLS
are the only programs you have using this driver, it will look for it in the
directory from which the LINETOOLS program was loaded if not found under
%SOUND%\DRV

Good places to obtain updated Creative Labs files is:

		Creative Labs web page:		http://www.creaf.com
		Creative Labs BBS system:	(405) 742-6660
		Creative Labs Compuserve Forum

		Creative Labs, Inc.  Technical Support
		1523 Cimarron Plaza, Stillwater, OK 74075 U.S.A.
		TEL (405) 742-6622		 	FAX (405) 742-6633

I apologize for the problems involved in finding suitable drivers for recent
cards, however I would like to point out that the audio interface was
developed (and made to rely on these files) using the guidelines set out in
Creative Labs own "Developer Kit for Sound Blaster Series"...


TESTSET - A telephone Set Simulator
-----------------------------------
TESTSET is a very precisely controllable telephone set/dialer.

TESTSET provides the ability to control SwitchHook flash timing, as well
as DTMF dialing tones duration, frequency, amplitude and waveform. The
waveform and amplitude of the high and low tones may each be configured
independantly, allowing for simulation of "twist" conditions.

TESTSET is very straightforward to use. Simply run it, and you will be
presented with a screen showing a dialing pad, discriptions of the
available command keys, and a history bar across the top of the screen
which shows the commands which have been entered:

	0-9,*,#,A-D	- Dial corresponding digit
	H			- Toggle hookswitch (Off-Hook/On-hook)
	F			- Generate a switch-hook flash (must be OFF-HOOK)
	P			- Wait for a pause interval
	E			- Erase the history bar
	M			- Set the sound card mixer levels
				  DTMF = Dtmf tone level
				  SPK  = Speaker level
	S			- Storage menu
					You may write/read the current configuration
					to/from a file.
	Q			- Quit program
	I			- Interval editor:
					Allows you to set the duration of DTMF, Flash and Pause:
					Note: All times are timed based on standard 8khz telco
					audio sampling. Even FLASH and PAUSE which are not
					associated with audio are timed by playing that many
					samples of silence.
	T			- Tone editor:
					You are presented with a screen where you can
					position a cursor on any of the tone frequencies
					in the DTMF tone pairs:
						PgUp/PgDn	= Increase/decrease value
						0-9			= Direct frequency entry
						BackSpace	= Correction of direct entry
						F1			= Undo changes to current digit
						F2			= Undo all changes
						F3			= Set current digit to standard value
						F4			= Set all digits to standard value
						ENTER		= Exit and save changes
						ESC			= Quit and discard changes
	W			- Waveform editor:
					Allows you to edit the waveform (shape and amplitude)
					of each of the High and Low tone pairs:
						SPACE		= Select "quadrant" to change
						Up/Down		= Raise/Lower amplitude
						Left/Right	= Shift transtion point at end of
									  selected quadrant Left or Right
						'S'/'F'		= Move the waveform within the selected
									  quadrant to be more Sine or Flat in
									  shape.
						'N'			= Restore waveform to pure sine wave.
						ENTER		= Exit and save changes
						ESC			= Quit and discard changes
	Q			- Quit / exit TESTSET


LINESCOPE - A telephone line analyser and audio storage scope
-------------------------------------------------------------
LINESCOPE is a multi-purpose tool for generating, playing, recording and
analysing tones and audio samples on a telephone line (or any other audio
medium).

General keys:
-------------
The following keys are "always available" within LINESCOPE:

  Left/Right	= Move view one display position to the left/right.

  PgUp/PgDn		= Move view one screen width to the left/right.

  Home/End		= Move view to beginning/end of the buffer.

  Up/Down		= Set vertical display gain (0-250%)

	This controls the "gain" applied to the displayed waveform. A value of
	100% means that one increment of the recorded signal value corresponds
	to one "dot" on the display screen.

	The 8-bit sample size means that the sample range covers 256 possible
	positions. The display area contains only 128 vertical dots per position,
	meaning that the default gain of 50% allows a fully modulated signal to
	exactly fill the display.

	Gain values above 50 may cause peak signals to fall outside of the display
	area. If this occurs, the signal will "stop" at the upper or lower edge of
	the display, and is shown in RED to indicate that it exceeds the available
	display area.

  Left/Right	= Set horizontal scale

	This controls the horizontal scale, which specifies how many samples
	occur in each display position. At full resolution (1), there is one
	display position for each sample. At (4) times resolution, each display
	position indicates a group of 4 samples (which are averaged into a
	single display dot).

	Lower horizontal scale values give you the most precise display.
	Higher horizontal scale values allow you to view more of the waveform
	in each screen.

	The horizontal scale value also controls the number of samples moved
	for each "step" of the display and bound controls. A useful trick if
	you wish to move the bound control a large distance, is to increase
	the horizontal scale, then move the control, then return to your
	original scale and find-tune the position of the bound.

  +/-			= Increase/Decrease vertical offset

	This controls the vertical position of the waveform within the display.
	'+' causes the display to shift upward, '-' causes the display to shift
	downward. If moving the display causes any points to fall outside of
	the display area, they will be shown in RED.

	This function is useful to separate the displayed waveforms when using
	the "overlay" function to view two waveforms at once.

  ^Home			= Reset display parameters

	This returns the display to:
		Vertical gain setting of 50.
		Horizontal scale setting of 1.
		Offset setting of 0.

  Tab			= Align to horizontal scale

	Shifts the display so that the first display position is an even
	multiple of the current horizontal scale setting.

  0-9,A-F		= Dial DTMF digit

  SPACE			= Toggle the function key groups.

	As SPACE is pressed, the function keys (F1-F10) will change definition
    and cycle through the groups listed below. Note that the key prompts
    will also change, giving you a visual indication as to which function
    group is currently active:

  E				= Toggle Entire/Bounded functions

	Toggles the operation of Play, Normalize and Statistics functions
	between the 'E'ntire buffer, and only the 'B'oundary region.

  H				= On/Off hook

	Toggles the hookswitch control, taking the interface off-hook
	or placing it on-hook.

  M				= Mixer Control

	Provides direct manual control of the sound card MIXER functions.
	Allows you to independantly set the Left and Right channel gain
	for the MASTER output, and each of the VOICE, MIDI, CDAUDIO, LINE
	and MIKE sources. Also allows you select the input source as LINE,
	MIKE, CDAUDIO or MIDI.

	Available keys are:
	  Up/Down		= Select Channel
	  Left/right	= Adj. both channels
	  Home/End		= Adj. left  channel only
	  PgUp/PgDn		= Adj. right channel only
	  Ins/Del		= Max/Min
	  ESC			= Exit

	To be compatible with the LINETEST line interface hardware, the
	INPUT source should be set to LINE, and all gains should be set to
	zero except for MASTER (Left+Right), LINE-Left (record level) and
	Voice-Right (Play level), however to accomodate other possible
	interfaces, the mixer function provides full control of all gains
	and inputs.

	At the top of the screen, a "bar graph" shows the current input
	level of the selected input source.

  O				= Set overlay mode

	Controls the display of the inactive buffer.
	Off:		No display
	'A'bsolute:	Inactive buffer is shown at it's last view position.
				(Ie: buffer display is fixed)
	'R'elative:	Inactive buffer is shown at it's last view position
				PLUS our current buffer offset (ie: buffer moves)
	When enabled, the inactive buffer trace is shown in GREEN.

  P				= Play audio

	Plays the audio sample in the current (Input or Output) buffer.
	Uses the 'E'ntire/'B'ounded flag to determine the region to play.

  Q				= Quit program

	Prompts with "Quit (Y/N?")
	Press 'Y' to terminate LINESCOPE.

  R				= Record audio

	Prompts for "Trigger level":
	  Enter a "trigger" value (0-127). The recording will only start
	  when a signal which exceeds this amplitude (positive or negative)
	  is received. A value of 0 will cause recording to begin immediately.
	Prompts for "Trigger edge":
	  Select "+" or "-", When "+" is selected, recording will begin with
	  the input signal exceeds the trigger value on the positive portion
	  of the waveform. When "-", recording begins when signal exceeds trigger
	  value
	Prompts with "#samples?"
	  Enter the number of samples which you wish to record in the buffer.
	Displays "WAITING FOR TRIGGER"
	Once the trigger value has been detected, the selected number of samples
	is recorded into the currently selected buffer.

  S				= Set scale mode

	Controls the operation of the numeric scale shown at the bottom of the
	display area:
		Absolute [Green]: Shows position from beginning of buffer
		Relative [Red]: Shows position from beginning of screen/display

  W				= DTMF Waveform

	Enters the waveform editor, allowing you to change the shape and
	amplitide of the DTMF tones waveform.
	See 'W' command under "TESTSET" (above) for more information.

	

System Control Functions
------------------------
  F1			= Toggle input/output buffer.

	LINESCOPE maintains two separate audio buffers. These are referred to
	as the "Input" and "Output" buffers, although for most purposes the
	operation of the buffers is identical. The use of two buffers allows
	you to manipulate two separate waveforms, typically one is used for
	audio recording, and one is used for audio generation.

  F2			= Load an audio file into current buffer
  F3			= Save an audio file from current buffer

	Audio files are stored in Creative Labs .VOC file format.

  F4			= Load LINESCOPE configuration/settings from file
  F5			= Save LINESCOPE configuration/settings to a file

	File is a proprietary .CFG format.

  F6			= Build a sinewave into current buffer

	If the buffer is NOT empty, first prompt is "Overlay (Y/N)?".
		Press 'N' to clear the buffer and build a new tone.
		Press 'Y' to mix the new tone into the existing buffer.
		  NOTE: When mixing into a buffer, the new tone adds to the content
		  of the buffer, and can cause overflow when the combined waveform
		  is generated. When build complex waveforms from several tones, the
		  amplitudes of all tones should sum to less than 100.
	Prompts with "Frequency?" - Enter the frequency you desire.
	Prompts with "#samples?" - Enter the number of samples to generate.
	Enters the waveform editor, allowing you to change the shape and
	  amplitide of the waveform to be generated. See 'W' command under
	  "TESTSET" (above) for more information.


  F7			= Play/Record

	Prompts with "#samples?"
	Enter the number of samples which you wish to record.
	Plays the content of the "output" buffer, then immediately records the
	requested number of samples into the "input" buffer.

  F8			= Statistics

	Calculates and displays satistics over the 'E'ntire or 'B'ounded region
	of the current buffer. These statistics include:
		- Highest signal level
		- Lowest  signal level
		- Average signal level
		- Average energy level (average of sum of + & - halves)
		- Number of zero crossings
		- Number of signal direction changes



Boundary Control Functions
--------------------------
LINESCOPE supports a "boundary", which allows you to mark a portion of
the wave form to be manipulated separately from the rest of the waveform.
The active "bounded" section is shown against a BROWN background (Normal
waveform is shown on a BLUE background).

  F1			= Move left boundary marker to the LEFT

  F2			= Move left boundary marker to the RIGHT

		(If left marker meets right marker, the right marker is also
		 moved to the right - ie: Left cannot pass right)

  F3			= Move right boundary marker to the LEFT

		(If right marker meets left marker, the left marker is also
		 moved to the left - Ie: Right cannot pass left)

  F4			= Move right boundary marker to the RIGHT

  F5			= Set both LEFT & RIGHT boundary markers to the current
				  display position.

  F6			= Position display to the location of the LEFT boundary.

  F7			= Position display to the location of the RIGHT boundary.

  F8			= Normalize

	Prompts for a new amplitude (0-100%), and calculates the (positive or
	negative) gain needed to make the highest/lowest peek in the buffer
	fit this amplitude. The calculated gain is then applied to each sample
	in the 'E'ntire or 'B'ounded region of the buffer.

	In other words, adjusts the gain of the entire so that the "loudest"
	portion reaches that given percentage of the maximum usable dynamic
	range.

  F9			= Crop

	Cuts away all portion of the waveform which is NOT within the left
	and right boundary markers. In other words, keeps only the bounded
	section of the waveform.

  F10			= Cut

	Cuts away the portion of the waveform which is within the left and right
	boundary markers. In other words, the bounded section is removed from
	the waveform.

A note about sample rate:
-------------------------
Several LINESCOPE commands allow you to specify a "sample rate".

This controls the rate at which samples are gathered during recording,
and the waveform granularity for the wave generation function.

The maximum sample rate supported by most sound card is 44,000 samples/sec.
Standard "telephone" quality is 8,000 samples/sec. LINESCOPE defaults to a
rate of 40,000 samples/sec. which gives good resolution, but is also easy
to scale to telephone quality (exactly 5 times).

LINESCOPES Input and Output buffers are limited to 65000 bytes in size.
This along with the sample rate determines the maximum length of an audio
block which can be manipulated.
	65000/40000	= 1.63 seconds
	65000/8000	= 8.13 seconds
