
================================================================
  OCTVQE8 - Zaptel Echo Canceller

  Copyright (C) 2007 OctWare Inc.
================================================================


* WHAT IS OCTVQE8?

  The OCTVQE Zaptel Echo Canceller (OCTVQE8) is a software package that 
  consists of a Linux executable that performs echo cancellation on systems
  that use the Zaptel driver. The application communicates with the Zaptel 
  driver through a kernel module.

  The application provides industry-leading echo cancellation and voice 
  quality enhancements for systems that rely on the Zaptel driver.


* INSTALLATION REQUIREMENTS
  
  The module must be installed on an x86 or x86-64 system running a Linux 
  distribution with a kernel of the 2.4 or 2.6 series. A working Zaptel 
  installation is needed.
  
  Outgoing traffic on TCP (enough permission to open an SSL session) must be
  allowed in order for the register utility to successfully communicate with
  OctWare's license server and finalize the registration process.  
  

* ARCHIVE CONTENTS

  The compressed OCTVQE - Zaptel Echo Canceller archives (in .tgz format) can
  be decompressed using the following command: 

    tar -zxpf octvqe8-01.00.00-base.tgz
    tar -zxpf octvqe8-01.00.00-<arch>.tgz

  Here are the contents of these archives:

    README:                This file.
    octvqeug5000-xxx.pdf:  The application's user guide, in PDF format. Refer
                           to this file for more information on using the
                           OCTVQE Zaptel Echo Canceller.
    ReleaseNotes.txt:      Release notes.
    octwareec1*.h:         These header files provide the hooks for the OctWare
                           Echo Canceller into the Zaptel interface. 
                           octwareec12.h is used with Zaptel version 1.2, 
                           octwareec14.h is used with Zaptel version 1.4. 
    octvqe/octvqe_linux.*: The OCTVQE kernel module source files.
    octvqe/octvqe_ioctl.h: The OCTVQE kernel module I/O control defines, for
                           channel statistics.
    octvqe/Makefile:       Makefile necessary to compile the OCTVQE kernel 
                           module.
    octvqe/octvqed:        The echo cancellation and VQE service binary.
    octvqe/octvqed.init:   Script to make the service auto-loading at system 
                           start-up.
    octvqe/octvqed.conf:   Channel parameters configuration file.
    
    
* BUILDING AND INSTALLING THE OCTVQE MODULE

  Run the following commands as root in a terminal in order to compile and 
  install the octvqe kernel module (the following assumes the Zaptel source
  is under /usr/src/zaptel):
  
    cd octvqe8-01.00.00
    cp -rf octvqe /usr/src/zaptel
    cd /usr/src/zaptel/octvqe
    make
    make install
    killall octvqed
    rmmod octvqe
    depmod
    modprobe octvqe  


* REBUILDING AND INSTALLING THE ZAPTEL MODULE

  Since the default Zaptel installation does not contain the OctWare OCTVQE 
  software, the Zaptel source files must be modified and recompiled. This 
  allows Zaptel to use the octvqed application for echo cancellation. The 
  following guidelines assume that the Zaptel source code is located in 
  /usr/src/zaptel. Here are the steps to follow in order to rebuild and install
  the Zaptel module.

  Copy the octwareecXX.h (replace XX by 12 when you have Zaptel 1.2.12 or 
  lower, or 14 when your version of Zaptel is above 1.2.12) file and the 
  include directory from the installation package to the Zaptel source 
  directory:

    cp octwareecXX.h /usr/src/zaptel
    cp -R octvqe /usr/src/zaptel
    cd /usr/src/zaptel

  Edit the zconfig.h file in order to define OctWare's echo canceller. Search
  within this file for the keyword ECHO_CAN and replace the default echo 
  canceller with the OctWare echo canceller by commenting out the built-in echo
  canceller and adding the following line:

    #define ECHO_CAN_OCTWARE

  Edit a Zaptel source file to include OctWare's echo canceller. The Zaptel 
  source file to edit depends on the version of Zaptel in use. If the version 
  of Zaptel is 1.2.12 or lower, zaptel.h needs to be edited; if the base 
  version is 1.4, zaptel.c needs to be edited; if the version is 1.2.13, 
  zaptel-base.c needs to modified. Search for the ECHO_CAN keyword and add the
  following lines (replace XX by 12 or 14 depending on your version):

    #elif defined(ECHO_CAN_OCTWARE)
    #define ZAPTEL_ECHO_CANCELLER "OCTEC" /* Only used in zaptel.h or .c */
    #include "octwareecXX.h"

  Run the following commands to compile and install the Zaptel drivers with 
  the new echo canceller: 

    make
    make install

  Remove the old Zaptel module (as well as any other Zaptel dependent modules)
  and reload the newly created Zaptel module:

    rmmod zaptel
    modprobe zaptel


* REGISTERING THE OCTVQED SERVICE

  The registration utility needs to be used to download a license that 
  activates channels. This has to be done only once, before starting the 
  octvqed service for the first time. Additional channel licenses can be 
  purchased and activated at any time.

  The registration utility can be downloaded from:
    
    http://www.octware.net/pub/register/
    ftp://ftp.octware.net/pub/register/

  Once the registration utility has been downloaded, change the permission on
  the file, to make it executable.  Then, launch the utility:

    chmod 500 register
    ./register
    
  If the register utility starts up correctly, enter the Activation-Key that 
  you have purchased.  Follow the on-screen instructions. Repeat the same 
  procedure if more then one license needs to be generated.
  
  The utility also supports a "batch" activation mode, where the 
  Activation-Keys are passed to the application using a file, one 
  Activation-Key per line. Use the -b option.


* STARTING THE OCTVQED SERVICE

  Start the echo cancellation service simply by running octvqed as root. The 
  application will detach from the calling terminal and will run in the 
  background.

    ./octvqed


* MORE INFORMATION

  Please refer to the accompanying octvqeug5000-xxx.pdf document for further
  information on using the OCTVQE Zaptel Echo Canceller.
  
  
  -- The OctWare team.
