From b764cf32306b0141a08a123dd377a9159949b26c Mon Sep 17 00:00:00 2001 From: russell Date: Thu, 29 Mar 2007 16:05:32 +0000 Subject: 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.2@2347 5390a7c7-147a-4af0-8ec9-7488f05a26cb --- README.hpec | 236 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 README.hpec (limited to 'README.hpec') 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. + -- cgit v1.2.3