Merged revisions 2347 via svnmerge from

https://origsvn.digium.com/svn/zaptel/branches/1.2

........
r2347 | russell | 2007-03-29 11:05:32 -0500 (Thu, 29 Mar 2007) | 3 lines

Add a README for HPEC, and add support for HPEC in the init script.
(issue #9413, chozian)

........


git-svn-id: http://svn.digium.com/svn/zaptel/branches/1.4@2348 5390a7c7-147a-4af0-8ec9-7488f05a26cb

1 files changed, 236 insertions, 0 deletions

diff --git a/README.hpec b/README.hpec
new file mode 100644
index 0000000..2c049f6
--- /dev/null
+++ b/README.hpec
@@ -0,0 +1,236 @@
+Digium High Performance Echo Cancellation (HPEC) README
+------------------------------------------------
+
+
+
+[Overview]
+
+Digium's HPEC is a commercially licensed, proprietary hybrid, echo cancellation
+solution for use with Digium and non-Digium Zaptel-compatible telephony
+interface cards. Its performance, in terms of its ability to eliminate echo,
+is superior to that of the open source routines normally included with Zaptel.
+
+HPEC is provided free of charge, with limited support, to in-warranty Digium
+analog interface cards. For out-of-warranty or non-Digium analog interface
+cards, HPEC is provided, with no support, for a per channel fee.
+
+Qualifying Digium customers may contact Digium directly for information about
+obtaining a free license. Non-Digium customers may visit the Digium web site
+at www.digium.com for information about purchasing a license.
+
+
+
+[Download Procedure]
+
+1) HPEC is integrated with the 1.2 and 1.4 releases of Zaptel, beginning with
+releases 1.2.13 and 1.4.1. In these releases you will notice a new
+sub-directory, "hpec," containing files related to HPEC.
+
+HPEC has been optimized for various 32-bit and 64-bit CPU architectures. You
+are welcome to try any or all of the various versions to see which provides the
+best performance on your server. To download the proper file, please connect
+via HTTP or FTP using one of the following URLs:
+
+(HTTP) http://ftp.digium.com/pub/telephony/hpec/
+(FTP)  ftp://ftp.digium.com/pub/telephony/hpec/
+
+There, you will find the directories "32-bit" and "64-bit." Please select the
+directory that corresponds to your CPU.
+
+Inside of the -bit directories, you will see files such as:
+
+hpec-8.20-i686.tar.gz
+
+Please download a copy of the file corresponding to your processor to your local
+system.
+
+* Command Line Example *
+# Log in as the user "root"
+cd /usr/src/zaptel-1.2/hpec
+wget http://ftp.digium.com/pub/telephony/hpec/32-bit/hpec-8.20-i686.tar.gz
+
+2) You must also download Digium's HPEC enabler tool via HTTP or FTP from the
+same location. The tool is called 'zaphpec_enable'. After the download has
+completed, you will need to mark the tool as 'executable'.  Then move it to the
+/usr/sbin directory.
+
+* Command Line Example *
+cd /root
+wget -v http://ftp.digium.com/pub/telephony/hpec/32-bit/zaphpec_enable
+chmod +x zaphpec_enable
+mv -f /root/zaphpec_enable /usr/sbin/
+
+3) You will also need Digium's product registration and activation tool. The tool can be 
+obtained from the following URLs:
+
+(HTTP) http://ftp.digium.com/pub/register
+(FTP)  ftp://ftp.digium.com/pub/register
+
+In this location, you will see directories for various operating system
+platforms (with processor architecture directories inside them). Since Zaptel
+is distributed only for the Linux kernel, you will need one of the tools
+from the 'linux' directory.
+
+* Command Line Example *
+cd /root
+wget http://ftp.digium.com/pub/register/32-bit/register
+chmod +x register
+
+
+
+[Installation Procedure]
+
+4) Having downloaded the necessary files, please decompress and untar the
+hpec-X.XX-CPU.tar.gz file as in the following example:
+
+* Command Line Example *
+cd /usr/src/zaptel-1.2/hpec
+tar -zxvf hpec-8.20-i686.tar.gz
+
+The following files will be extracted:
+LICENSE
+hpec_x86_32.o_shipped
+
+5) Please review the enclosed LICENSE file before installing this software.
+You must agree to its terms before using the software.
+
+* Command Line Example *
+less LICENSE
+
+6) Please rebuild and install Zaptel as you normally would.
+
+* Command Line Example *
+cd /usr/src/zaptel-1.2
+make
+make install
+
+7) Next, we need to perform registration of your system for use with HPEC. With
+a copy of your registration key on hand, please run the registration utility.
+During the registration process, please select "Digium" as the product vendor,
+and "High Performance Echo Canceller" as the product type. When prompted,
+please enter your key as in the following example:
+
+* Command Line Example *
+cd /root
+./register
+
+And, when prompted for the key, as in the following example:
+HPEC-ABC123
+
+Your server is required to have Internet access in order to register your HPEC
+key for licensed use. Outgoing network traffic on TCP port 443 (SSL) must be
+allowed in order for the registration utility to successfully communicate with
+Digium's license server and complete the registration process. The name of the
+first Ethernet device on your server must be eth0 in order for the registration
+process to complete successfully. The registration process will not be 
+successful if the first Ethernet devices is eth1, eth2, etc.
+
+8) The registration utility will notify you of a successful registration.
+
+9) Please load the zaptel kernel module as in the following example:
+
+* Command Line Example *
+modprobe zaptel
+
+You will see a notice on the console about Digium's HPEC having been loaded as
+part of the Zaptel module.
+
+10)  In order to activate HPEC, you will have to run the zaphpec_enable
+utility. This utility must be run after loading the Zaptel kernel module, and
+not before. If this utility is not run, the Zaptel module with HPEC support
+will not be able to perform echo cancellation. If this utility is run
+successfully, echo cancellation will occur.
+
+Run the utility as in the following example:
+
+* Command Line Example *
+/usr/sbin/zaphpec_enable
+
+If the execution is successful, the Zaptel kernel module is loaded, and a valid
+Digium HPEC license key is present on the system, the utility will display to the
+console the number of channels available.
+
+
+
+[Usage Notes]
+
+You may have the zaphpec_enable utility run automatically at boot time for
+Redhat/Fedora and Debian distributions by running "make install" in the source
+directory of the latest version of Zaptel.
+
+Use of HPEC inside of Asterisk is controlled by the zapata.conf configuration
+file, generally found as:
+
+/etc/asterisk/zapata.conf
+
+HPEC is controlled by the:
+
+echocancel=
+
+option inside of zapata.conf.
+
+This option is configured with a length, in taps, of echo cancellation to be
+performed. For example, to set a length of 128ms (1024 taps), the appropriate
+setting would be:
+
+echocancel=1024
+
+To set a length of 32ms (256 taps), the appropriate setting would be:
+
+echocancel=256
+
+Since HPEC is a software solution, you may have to take into consideration the
+power of your CPU. Tap lengths of smaller values consume less CPU, but
+provide echo cancellation within a shorter window. Tap lengths of larger
+values provide echo cancellation over a longer time / distance, but consume
+more CPU.
+
+The following values of the echocancel option in zapata.conf are acceptable
+for use with HPEC:
+
+128   -(16ms)
+256   -(32ms)
+512   -(64ms)
+1024 -(128ms)
+
+[Backup Procedure]
+
+It is extremely important that you backup all of the files located in the
+/var/lib/digium/licenses directory. This directory contains the Host-ID
+specific license files for your system. These license files are tied to the
+MAC address of all the ethernet devices installed in your system. Creating a
+backup of this directory will allow you to restore your HPEC license file in
+case you need to reinstall your operating system. This will help prevent the need
+to contact Digium to request authorization to increment your
+HPEC key and from needing to purchase a new HPEC key if you exceed the
+maximum number of HPEC key increments allowed.
+
+
+
+[General Notes]
+
+- Multiple HPEC keys may be registered to the same server. This enables the 
+  increase of the total number of available HPEC licensed channels on your
+  server. New HPEC keys may be registered to your Asterisk server using the
+  same instructions provided in the Installation Procedure section. There will
+  be an additional HPEC license file generated in the /var/lib/digium/licenses
+  directory for each HPEC key that is successfully registered to your server.
+  It is extremely important that you follow the instructions provided in the
+  Backup Procedure section whenever a new HPEC key is successfully registered
+  to your server.
+
+- An HPEC key must be re-registered if any of the Ethernet devices in your
+  server are changed, added, or removed. The unique HPEC license file located
+  in your /var/lib/digium/licenses directory is tied to the MAC address of all
+  the Ethernet devices installed in your system. An HPEC key can only be 
+  re-registered once without authorization from Digium. Digium must be contacted
+  by phone in order to request authorization to have your HPEC key incremented.
+  Digium reserves the right to deny authorization for having an HPEC key
+  incremented.
+
+----------------------------
+
+Contact the Digium Technical Support Department by phone, either toll free at
+1-877-LINUX-ME (1-877-546-8963) or locally at 1-256-428-6000, if you have any
+questions or concerns. You may also contact us by e-mail at support@digium.com. 
+