Open Source Line Echo Canceller (OSLEC)

[[introduction]] Introduction

Oslec is an open source high performance line echo canceller. When used with Asterisk it works well on lines where the built-in Zaptel echo canceller fails. No tweaks like rxgain/txgain or fxotrain are required. Oslec is supplied as GPL licensed C source code and is free as in speech.

Oslec partially complies with the G168 standard and runs in real time on x86 and Blackfin platforms. Patches exist to allow any Zaptel compatible hardware to use Oslec. It has been successfully tested on hardware ranging from single port X100P FXO cards to dual E1 systems. Hardware tested includes TDM400, X100P, Sangoma A104, Rhino E1 etc. It also works well on the link:ip04.html[IP04 embedded Asterisk platform].

There is also a project underway to use http://peter.schlaile.de/mISDN/[OSLEC with mISDN].

Oslec is included in many distributions, including Debian, Gentoo, Trixbox, Elastix, and Callweaver.

[[testimonials]] Testimonials

So how good is Oslec?

The http://www.trixbox[Trixbox] community have been testing Oslec, here is a http://www.trixbox.org/forums/trixbox-forums/open-discussion/need-people-echo-problems[Trixbox forum thread] that has feedback from many people. Start about half way down the page, or search on the string "night and day" :-)
The http://callweaver.org/wiki/Zaptel[CallWeaver] project use and recommend Oslec.
Here is some feedback from Oslec users:

[Gordon Henderson, posted in the Asterisk-user mailing list July 21 2008]

I switched to OSLEC after testing HPEC on TDM400 boards, and found that it worked much better and wasn't limited to the restricted mechanism Digium uses for licensing (unlikely as it sounds, I have some clients who do not have a connection to the public Internet, and never will for their phone system)

It also passes the wife test which HPEC didn't.

It's also free (OS as in Open Source), which HPEC isn't, although that wasn't my primary reason for using it - ease of use and "workability" was.

[Michael Gernoth, Author of the Zaptel MG2 echo canceller]

Thanks for OSLEC, it's so much better than my hacked KB1 which is called MG2 :-)

[David Gottschalk]

Once I managed to get OSLEC installed (it was a big job for me, because I was missing many of the dependancies and knowledge), it immediately fixed the echo problems I had been unable to get rid of to date despite lots and lots of tweeks, tests and fiddling. Even more suprisingly, it appears to converge almost immediately from my initial test.

This code is the best since thing since, well, Asterisk !!!

[Nic Bellamy, Head Of Engineering; Vadacom Ltd]

Short version: KB1 < MG2 < OSLEC < HPEC

In the open source line echo canceller category, OSLEC is so far the best I've seen.

It converges reasonably fast, and thanks to it's dual-path approach, will converge, albeit a bit slowly, on nasty echo paths where cancellers like KB1 and MG2 will fail entirely.

The nonlinear processor and comfort noise generator provide for a far more pleasant listening experience than KB1/MG2.

It's not quite up to the grade of ADT's G.168 canceller used in Digiums HPEC product in terms of convergence speed or tail coverage.

[Pawel Pastuszak, Astfin.org]

Since I installed the first version of OSLEC I was hooked.... It's been several months now since the alpha version was released; after using OSLEC Mark and I agreed that we had to have OSLEC as the main echo cancellation in the Astfin distribution.

[Pavel Selivano, Parabel Ltd]

I've been working with Oslec since March of 2007. Oslec has had some problems, but, thanks to David, they are solved. Now, I can say Oslec is time-tested. The best, I can note - it is still under development (with feed-back). Thank you David for your good deed.

BTW: comparison to Intel IPP's echo canceler have shown, Oslec is very good :-)

[[news]] Oslec News

Saturday, June 7, 2008: We have worked out how to use <<rhino,Oslec with Rhino>> PRI cards. Thanks Juan Manuel Coronado!
Friday, May 16, 2008: Oslec Road Map. I have kicked off a discussion of the http://sourceforge.net/mailarchive/forum.php?thread_name=1210895745.7127.60.camel%40localhost&forum_name=freetel-oslec[development roadmap] for Oslec. Is hardware echo cancellation headed for extinction?
Friday, May 16, 2008: Oslec chosen as the default http://sourceforge.net/mailarchive/forum.php?thread_name=20080515131239.GJ27523%40xorcom.com&forum_name=freetel-oslec[echo canceler for Debian]. Thanks Tzafrir for your work on packaging Oslec for Debian!
Tuesday, May 13, 2008: link:/blog/?p=64[Oslec versus the SPA 3000] ATA. A blog post comparing the SPA 3000 echo cancellation to Oslec on a problem FXO line.
Wednesday, February 11, 2008: Oslec mailing list created. Due to popular demand (well, Tzafrir mainly!) there is now an https://lists.sourceforge.net/lists/listinfo/freetel-oslec[Oslec mailing list].
Sunday, February 10, 2008: Zaptel 1.4.8 patch checked into SVN, thanks Tzafrir.

[[install]] Installing OSLEC with Asterisk/Zaptel

Notes:

This process also installs a system for sampling echo signals that is helpful for developing oslec.
I assume Asterisk is already installed and tested.
I assume you are running Linux 2.6 and Zaptel 1.2.13 or a later 1.2/1.4 version of Zaptel.
I assume you are using a Digium TDM400 line interface card. Change the "insmod wctdm.ko" line below to match your line interface hardware (e.g. wcfxo for a X100P).
For Zaptel 1.4.x replace the 1.2.13 text below 1.4.x (tar ball and patch file).
For Linux 2.4 replace the "insmod moduleXYZ.ko" lines below with "insmod moduleXYZ.o".

1/ Download, build and install oslec:

$ cd ~ $ wget http://www.rowetel.com/ucasterisk/downloads/oslec-0.1.tar.gz $ tar xvzf oslec-0.1.tar.gz $ cd oslec-0.1 $ make $ insmod kernel/oslec.ko

Optional: If you want the latest and greatest, replace the "wget" step with:

$ svn co http://svn.astfin.org/software/oslec/trunk/ oslec

NOTE: There are patches for Zaptel 1.2.13, 1.2.18, 1.2.24, 1.4.1, 1.4.3, 1.4.4, 1.4.7.1, 1.4.8, 1.4.9.2 and 1.4.11. It's quite easy to port to other versions, please feel free to send me a new patch should you get Oslec working with another Zaptel version. If you can't see a patch for your Zaptel version try http://svn.astfin.org/software/oslec/trunk/kernel[Oslec SVN] for the latest patches.

2/ Build, patch and install Zaptel. First obtain zaptel-1.2.13.tar.gz and:

$ tar xvzf zaptel-1.2.13.tar.gz $ cd zaptel-1.2.13 $ ./configure $ patch < ../oslec-0.1/kernel/zaptel-1.2.13.patch (see note 1 below) $ cp ../oslec-0.1/kernel/dir/Module.symvers . (see note 2 below) $ make $ insmod zaptel.ko $ insmod wctdm.ko $ ./ztcfg $ asterisk

NOTE: 1: Use -p1 option for zaptel-1.4.9.2 and above

NOTE: 2: The "cp Module.symvers" step above is optional on many systems; it stops warnings like WARNING: "oslec_echo_can_create" [zaptel.ko] undefined!". However on some Linux machines zaptel will not compile without this step.

3/ These options in zapata.conf are important:

echocancel=yes
echocancelwhenbridged=no
;echotraining=400

The echocancelwhenbridged=no allows faxes to pass from FXS to FXO ports without interference from the echo canceller. This option is important for fax signals.

Make sure echotraining is disabled when using Oslec - this is not supported and if enabled will cause the channel to be silent (i.e. no audio will pass through).

4/ The settings above have been shown to reliably cancel echo in 95% of cases. If you can still hear echo you may have one of the rare cases where your echo is longer than 16ms. To configure Oslec with a 32ms tail:

echocancel=256
echocancelwhenbridged=no
;echotraining=400

Then restart Asterisk.

[[pbxinaflash]] PBX in a Flash Install

Here are the http://pbxinaflash.com/forum/showthread.php?t=100&page=3[Oslec install procedure] for PBX in a Flash. Check the 7-24-08 post in this thread by Alex728 for Zaptel-1.4.11 instructions. Thanks JD Austin and Alex.

Matt Keys has suggested that the PBX in a Flash install procedure also worked well for Ubuntu server.

[[rhino]] Rhino PRI cards

The rhino-2.2.6 driver for Rhino PRI cards has software echo cancellation disabled by default. This means there is no echo cancellation unless you opt for the Rhino hardware echo cancellation module. However the driver is easy to hack to enable software echo cancellation, and hence Oslec.

In the rhino-2.2.6 driver, file r1t1_base.c, r1t1_receiveprep function, arou

Oslec

Install / Use

README