README.txt for Open Source Line Echo Canceller (OSLEC)
Created David Rowe 15 Jan 2007

Introduction
------------

Oslec is a work in progress code for a G168 open source line echo
canceller.  The e/c is being developed against the G168 standard
(available from the ITUT website).  The e/c is a development of the
partially complete code from Steve Underwood's spandsp library.

The most important files are:

spandsp/src/echo.c         : the echo canceller
spandsp/tests/echo_tests.c : suite of G168 tests and automatic test code

This repository combines several projects (mainly spandsp) used to
develop and test oslec.  The idea is that after oslec matures the core
echo canceller will be officially added to spandsp, however in the
mean time this repository is being maintained so that the interim
source files can be version controlled, and that all the test programs
and real time kernel modules can be easily tied together.

Status
------

As of 16 Feb 2007:

1/ The simulation code passes many but not all of the G168 tests.
Some problems with high level signals near 0dBm0 and some of the G168
echo models.  Passes maybe 90% of the tests attempted so far, however
not all of the tests and/or range of test conditions have been
attempted yet.  The fails are close calls (like a few dB off), not
complete breakdowns of the algorithm.

2/ Real time runs well on FXO/FXS lines where the other Zaptel echo
cancellers (including the latest MG2) struggle.  No tweaks like
levels, fxotrain, or even opermode required so far.  Hardware used for
tests was a TDM400 card.

3/ Real time currently has the following problem:

  + X100P line interface hardware where it converges slowly (5
  seconds) due (I think) to 60Hz hum in the rx signal.  The TDM400 has
  no DC offset or hum due to different chipset employed (Silicon
  Labs).  Some high pass filtering has shown to help this a lot in
  simulation, but the filter needs to be ported to fixed point (TBC).

Further Reading
---------------

The http://www.rowetel.com/blog/?p=23[Open Source Echo Canceller]
multi-part series on my blog.

Directories
-----------

spandsp : Needs no introduction.

user....: User mode apps, e.g. real time sampling of echo signals using
          the zaptap system.  These samples are useful for test and
          development of oslec.  README for zaptap also lives here at
          present.

kernel..: Oslec in kernel module form and patches to use Zaptap and oslec
          with Zaptel.

HowTo - Run OSLEC with Asterisk/Zaptel
--------------------------------------

Notes:

+ This process also installs link:/zaptal.html[Zaptap] - 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
  version of Zaptel.

+ I assume you are using a Digium TDM400 line interface card.  Change
  the "insmod wctdm.o" line below to match your line interface
  hardware.

+ For Zaptel 1.4.0 replace the 1.2.13 text below 1.4.0 (tar ball and
  patch file).

+ For Linux 2.4 replace the "insmod moduleXYZ.ko" lines below with
  "insmod moduleXYZ.o".

1/ Build and install oslec:

  $ cd ~
  $ svn co http://svn.rowetel.com/software/oslec/trunk/ oslec
  $ cd oslec/kernel
  $ make
  $ insmod zaptel.ko 

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
  $ patch < ../oslec/kernel/zaptel-1.2.13.patch
  $ make
  $ insmod zaptel.ko
  $ insmod wctdm.ko 
  $ ./ztcfg
  $ asterisk

Run Time Information
--------------------

Set up a call that uses an analog port, then check out /proc/oslec for
real-time stats:

  [root@homework kernel]# cat /proc/oslec/info
  channels....: 1
  mode........: [13] |ADAPTION|NLP|CNG|
  Ltx.........: 0
  Lrx.........: 211
  Lclean......: 211
  Lclean_bg...: 211
  shift.......: 0
  Double Talk.: 1
  MIPs (last)....: 1
  MIPs (worst)...: 7
  MIPs (avergage): 1

You can turn the various mode switches off and on, for example:

   echo 9 > /proc/oslec/mode

turns off comfort noise, but keeps ADAP and NLP on.  The /proc
interface only monitors the first Zaptel call you bring up, see
kernel/oslec_wrap.c for more information.
   
There is also a shell script that implements a GUI for run-time
control of oslec.  For example you can change the NLP mode
in real time, as you are speaking.

  $ cd kernel
  $ ./oslec-ctrl-panel.sh 

HowTo - Run the OSLEC G168 Simulation
-------------------------------------

1. Read spandsp-0.0.3/README and make sure you have installed the
dependencies like libtiff-devel, libaudiofile-devel, fftw-devel.

2. Make, build, run a test:

  $ cd spandsp-0.0.3; 
  $ ./configure --enable-tests
  $ make
  $ cd tests
  $ ./echo_tests 2a

3. You can change the echo path model with -m [1..7] (default 1)

4. You can change the ERL with -erl [0..whatever] (default 10.0)

5. You can plot the internal states using Octave:

  $ cd spandsp-0.0.3/echo_tests
  $ octave
  octave:1> echo_dump

  The st= and en= statements at the top of echo_dump.m control which
  part of the waveform is plotted.

6. There are some sequences of tests set up in the script files:

  $ ./g168_quick.sh (useful for a quick sanity test)
  $ ./g168_tests.sh (more comprehensive set of tests)

7. For more options:

  $ ./echo_tests -h