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 DAHDI-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 DAHDI. [Download Procedure] 1) HPEC is integrated with DAHDI. In the dahdi-linux-complete source package, you may notice the linux/drivers/dahdi/hpec sub-directory which contains files related to HPEC. Note: All examples in this README will refer to the "linux/drivers/dahdi/hpec" sub-directory. 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 "x86-32" and "x86-64". Please select the directory that corresponds to your CPU architecture. Then you will be presented with files such as: hpec-10.04.001-i686.tar.gz Please download a copy of the file corresponding to your processor type to your local system. First, log in as the user "root". Command-line Example: # cd /usr/src/dahdi-linux-complete-2.1.0.4+2.1.0.2/linux/drivers/dahdi\ /hpec # wget -v http://downloads.digium.com/pub/telephony/hpec/x86-32/\ hpec-10.04.001-i686.tar.gz 2) You must also download Digium's HPEC enabler tool via HTTP from the same location. The tool is called 'dahdihpec_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/x86-32/\ dahdihpec_enable # chmod +x dahdihpec_enable # mv -f /root/dahdihpec_enable /usr/sbin/ 3) You will also need Digium's product registration and activation tool. This tool can be obtained from the following URL: http://downloads.digium.com/pub/register There, you will find the directories "x86-32" and "x86-64". Please select the directory that corresponds to your CPU architecture. Please download a copy of the register utility to your local system. Command Line Example: # cd /root # wget -v http://downloads.digium.com/pub/register/x86-32/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/dahdi-linux-complete-2.1.0.4+2.1.0.2/linux/drivers/dahdi\ /hpec # tar -zxvf hpec-10.04.001-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 DAHDI as you normally would. Command-line Example: # cd /usr/src/dahdi-linux-complete-2.1.0.4+2.1.0.2/linux # 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. Command-line Example: # cd /root # ./register 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: 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. You must have at least one Ethernet device in your Asterisk server in order for the registration process to complete successfully. 8) The registration utility will notify you of a successful registration. 9) Please load the 'dahdi' kernel module as in the following example: Command-line Example: # modprobe dahdi 10) In order to activate HPEC, you will have to run the dahdihpec_enable utility. This utility must be run after loading the DAHDI kernel module, and not before. If this utility is not run, the DAHDI 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/dahdihpec_enable If the execution is successful, the DAHDI 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 DAHDI modules, you will need to re-run the dahdihpec_enable utility to enable usage of the HPEC. 11) You may have the dahdihpec_enable utility run automatically at boot time for Redhat/Fedora and Debian distributions by running "make config" in the source directory of the latest version of DAHDI. This will install an init script and symlinks for DAHDI which will execute dahdihpec_enable if an HPEC license is registered on your system. [Configuration Procedure] 12) DAHDI uses modular echo cancellers that are configured per channel. The echo cancellers are compiled and installed as part of the dahdi-linux package. You can specify the echo canceller to be used for each channel. The default behavior is for there to be no echo canceller on any channel. So, it is very important that you specify one in the system.conf file if you do not have hardware echo cancellers and need echo cancellation. The format is: echocanceller=, A list of valid echo cancellers are specified in the sample system.conf file. The following is a typical setup using HPEC echo cancellation on an analog card with 8 FXO ports: echocanceller=hpec,1-8 13) Use of HPEC inside of Asterisk is controlled by the chan_dahdi.conf configuration file, generally found as: /etc/asterisk/chan_dahdi.conf HPEC is controlled by the: echocancel= option inside of chan_dahdi.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 will need to take into consideration the processing power of your CPU. Tap lengths of smaller values consume less CPU resources, 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 resources. The following values of the echocancel option in chan_dahdi.conf are acceptable for use with HPEC: 128 - (16ms) 256 - (32ms) 512 - (64ms) 1024 - (128ms) [Backup Procedure] 14) 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 can 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-DIGIUM-1 (1-877-344-4861) 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.