		Open H.323 PSTN Gateway Sample Code
		-----------------------------------


Introduction
============

This is a very simple PSTN to H.323 gateway program using the OpenH323
library. It allows H.323 clients to make outgoing calls, and incoming
calls to be routed to a specific H.323 client.

To make an outgoing call, you must have a client that supports PSTN
gateways. The OpenH323 OhPhone and OpenPhone clients work, and NetMeeting
should work though only using G.711.

Some support for other clients is provided. If a H.323 client calls the
gateway with no gateway information, and the -d option was used then that
number is automatically called.

Usage
=====

Usage : pstngw [options] [ line1client ] [ line2client ... ]
Options:
  -q --quicknet dev   : Use Quicknet LineJACK
  -v --vpb dev        : Use Voicetronix V4PCI or VPB4
  -u --username str   : Set local endpoint name
  --aec num           : Set AEC (default to medium) - Quicknet card only
  -d --dial phone     : Default number to call
  -t --trace          : Enable trace, use multiple times for more detail
  -o --output         : File for trace output, default is stderr
  -h --help           : Display this help message
  --listenport        : The port to listen on for connections. (default 1720)
**Note: Also see 'pstngw --help' for more options

  line1client, line2client ... are IP addresses or domain names of the computer
			       running a H323 application you want to connect
			       the PSTN call to.
			       If there are several H323 applications on one
			       machine, you can also specify the port to connect
			       to with machine_name:port  eg mybox.com:2000

Voicetronix Quickstart - Linux
==============================

1. From www.voicetronix.com.au download the Voicetronix driver.  This file will 
   have the file name vpb-driver-x.y.z.  For use with pstngw, make sure the driver
   is version 2.2.5 or greater.  Make, install and test the Voicetronix driver.
   See Voicetronix README for more information.  

2. The gateway software requires the Voicetronix hardware to be able to detect
   dial and hangup tones.  The dial tone detector detects dial tone, the busy tone 
   detector detects hangup.  The nature of these tones (frequency, cadence etc)
   varies from country to country and on different PBXes.  It is therefore very
   likely that you will need to program the Voicetronix driver for your specific
   dial and busy tones.  There are instructions on programming tone detectors in
   the Voicetronix driver README.  Use the environment variable method to set up
   the tone detectors.
   
   For a quick start you can igniore this step, however you may find the gateway
   software does not terminate calls correctly, and the --collect option may not
   work.

3. Also from www.voicetronix.com.au download pstngw_patch-x.y.tar.gz.  This 
   contains the latest versions of several files needed to patch the openh323 code
   to  work correctly with the Voicetronix hardware.  Untar (tar xzvf) this file.

4. From www.openh323.org download the lastest pwlib, openh323, and pstngw .tar.gz 
   packages.  Login as root.  Untar (tar xvzf package) the packages into 
   your /root (root home) directory.

5. Before compiling the packages from (4), copy the following files from 
   pstngw_patch.x.y into the openh33 packages:

   openh323/vpblid.cxx -> ~/openh323/src
   openh323/vpblid.h -> ~/openh323/include
   pstngw/main.cxx -> ~/pstngw/
   pstngw/main.h -> ~/pstngw/
   pstngw/ReadMe.txt -> ~/pstngw

   Note: 'make install' in the pstngw-patch directory will perform these steps 
   IF you have un-tarred openh323 and pstngw in your /root directory.  Otherwise
    copy manually.

6. Compile pwlib, openh323, and pstngw in that order.  See the Readme.txt in each 
   package for more information.  Use 'make debug' to compile these packages. The
   packages take some time (around 30 minutes on a P800) to compile.

7. Typical starting options:
 
a) OpenPhone to Gateway
-----------------------

cd to pstngw directory
./obj_linux_x86_d/pstngw -v 1 --no-gatekeeper -P GSM

The gateway PC should now accept calls from the OpenPhone H323 client.  To get the
gateway to dial a number, enter the h323 calling address in the form number@host, 
e.g. 1234@gatewaypc.com

OpenPhone is a Win32 H323 client available from www.openh323.org

Break-up of OpenPhone Audio
---------------------------

When I first ran OpenPhone on my Win32 laptop I experienced lots of break up in the
receive audio.  I fixed as follows:
+ Options-Audio->Options
+ change sound buffers to 10
+ jitter buffer 150ms

b) NetMeeting to Gateway
------------------------

The only common codec NetMeeting and pstngw/Voicetronix support is mulaw. Run
the gateway with:

./obj_linux_x86_d/pstngw -v 1 --no-gatekeeper

To call the gateway using NetMeeting:
+ enter the machine name in the box to the left of the telephone icon
+ click on the telephone icon

To dial out a number using NetMeeting:

+ Tools-Options-Advanced Calling
+ In the "gateway settings" box check the box "Use a gateway to call...."
+ enter the machine name of the gateway machine
+ go back to the main GUI of NetMeeting
+ enter the number to be dialled (not the machine name) in the box to the left of
  the telephone icon
+ click on the telephone icon

c) PhoneJack to Gateway
-----------------------

Install the openphone package (available from www.openh323.org) and the Quicknet
PhoneJack hardware. Run openphone with the gsm option:

./ohphone -l -q /dev/phone0 --playvol 50 --gsm -n  

Run the gateway software as in (a)

d) Gateway A to Gateway B
-------------------------

Gateway A (host name gatewaya):

cd to pstngw directory
./obj_linux_x86_d/pstngw -v 1 gatewayb [...] --no-gatekeeper -P GSM --collect

Gateway B (host name gatewayb):

cd to pstngw directory
./obj_linux_x86_d/pstngw -v 1 gatewaya [...] --no-gatekeeper -P GSM --collect

Note: In [...] place 'gatewayb gatewayb gatewayb.......' for as many lines as
your have hardware for.  For example, for one V4PCI card, their should be a
total of 4 host names.
 
d) Dialing Options
------------------

When making gateway to gateway calls, there are three dialling options:

1) If -d is used, the gateway accepting the call dials the number supplied 
   on the command line.

2) If no dialling options are used, the gateway accepting the call just takes
   the line offhook, the caller will then hear dialtone through the VOIP link.
   The caller can then dial the number to be called from Gateway B, however as
   the DTMF tones are passing through the codecs, there may be problems
   with accurate DTMF detection at the other end, leading to dialling errors.
   Real-time out of band dialling (using the Voicetronix hardware) has not 
   been implemented yet.

3) If --collect is used, the number to call is collected by Gateway A before
   the H323 call is made.  When the caller dials into Gateway A:
   - on answering gatewaya generates a dialtone
   - the caller then enters the digits to be dialled from Gateway B
   - when finished, the user presses #, or waits for the timeout
   - the H323 call then commences
   - when Gateway B goes off hook, the number is dialled by Gateway B     

8) Support
----------

For support with the Voicetronix hardware please contact:

David Rowe david@voicetronix.com.au





