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 1.2 releases and 1.4 releases prior to 1.4.9, you will notice a new sub-directory, "hpec," containing files related to HPEC. As of 1.4.9, the sub-directory is "kernel/hpec." Note: All examples in this README will refer to "kernel/hpec." If you are using a release prior to 1.4.9, you will need to replace this with "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 to the following URL: http://downloads.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-9.00.002-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.4/kernel/hpec wget http://downloads.digium.com/pub/telephony/hpec/32-bit/hpec-9.00.002-i686.tar.gz 2) You must also download Digium's HPEC enabler tool via HTTP 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://downloads.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 URL: http://downloads.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://downloads.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.4/kernel/hpec tar -zxvf hpec-9.00.002-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.4 ./configure # Note, this is only required with Zaptel 1.4 or later. 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. NOTE: If for any reason you need to unload and reload the Zaptel modules, you will need to re-run the zaphpec_enable utility to enable usage of the HPEC. [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.