modem_echo.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * modem_echo.h - An echo cancellor, suitable for electrical echos in GSTN modems
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2001, 2004 Steve Underwood
00009  *
00010  * Based on a bit from here, a bit from there, eye of toad,
00011  * ear of bat, etc - plus, of course, my own 2 cents.
00012  *
00013  * All rights reserved.
00014  *
00015  * This program is free software; you can redistribute it and/or modify
00016  * it under the terms of the GNU General Public License as published by
00017  * the Free Software Foundation; either version 2 of the License, or
00018  * (at your option) any later version.
00019  *
00020  * This program is distributed in the hope that it will be useful,
00021  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00022  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00023  * GNU General Public License for more details.
00024  *
00025  * You should have received a copy of the GNU General Public License
00026  * along with this program; if not, write to the Free Software
00027  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00028  *
00029  * $Id: modem_echo.h,v 1.5 2005/12/10 12:56:20 steveu Exp $
00030  */
00031 
00032 /*! \file */
00033 
00034 #if !defined(_MODEM_ECHO_H_)
00035 #define _MODEM_ECHO_H_
00036 
00037 /*! \page modem_echo_can_page Line echo cancellation for modems
00038 
00039 \section modem_echo_can_page_sec_1 What does it do?
00040 This module aims to cancel electrical echoes (e.g. from 2-4 wire hybrids)
00041 in modem applications. It is not very suitable for speech applications, which
00042 require additional refinements for satisfactory performance. It is, however, more
00043 efficient and better suited to modem applications. 
00044 
00045 \section modem_echo_can_page_sec_2 How does it work?
00046 The heart of the echo cancellor is an adaptive FIR filter. This is adapted to
00047 match the impulse response of the environment being cancelled. It must be long
00048 enough to adequately cover the duration of that impulse response. The signal
00049 being transmitted into the environment being cancelled is passed through the
00050 FIR filter. The resulting output is an estimate of the echo signal. This is
00051 then subtracted from the received signal, and the result should be an estimate
00052 of the signal which originates within the environment being cancelled (people
00053 talking in the room, or the signal from the far end of a telephone line) free
00054 from the echos of our own transmitted signal. 
00055 
00056 The FIR filter is adapted using the least mean squares (LMS) algorithm. This
00057 algorithm is attributed to Widrow and Hoff, and was introduced in 1960. It is
00058 the commonest form of filter adaption used in things like modem line equalisers
00059 and line echo cancellers. It works very well if the signal level is constant,
00060 which is true for a modem signal. To ensure good performa certain conditions must
00061 be met: 
00062 
00063     - The transmitted signal has weak self-correlation.
00064     - There is no signal being generated within the environment being cancelled.
00065 
00066 The difficulty is that neither of these can be guaranteed. If the adaption is
00067 performed while transmitting noise (or something fairly noise like, such as
00068 voice) the adaption works very well. If the adaption is performed while
00069 transmitting something highly correlative (e.g. tones, like DTMF), the adaption
00070 can go seriously wrong. The reason is there is only one solution for the
00071 adaption on a near random signal. For a repetitive signal, there are a number of
00072 solutions which converge the adaption, and nothing guides the adaption to choose
00073 the correct one. 
00074 
00075 \section modem_echo_can_page_sec_3 How do I use it?
00076 The echo cancellor processes both the transmit and receive streams sample by
00077 sample. The processing function is not declared inline. Unfortunately,
00078 cancellation requires many operations per sample, so the call overhead is only a
00079 minor burden. 
00080 */
00081 
00082 #include "fir.h"
00083 
00084 /*!
00085     Modem line echo canceller descriptor. This defines the working state for a line
00086     echo canceller.
00087 */
00088 typedef struct
00089 {
00090     int adapt;
00091     int taps;
00092 
00093     fir16_state_t fir_state;
00094     /*! Echo FIR taps (16 bit version) */
00095     int16_t *fir_taps16;
00096     /*! Echo FIR taps (32 bit version) */
00097     int32_t *fir_taps32;
00098 
00099     int tx_power;
00100     int rx_power;
00101 
00102     int curr_pos;
00103 } modem_echo_can_state_t;
00104 
00105 /*! Create a modem echo canceller context.
00106     \param len The length of the canceller, in samples.
00107     eturn The new canceller context, or NULL if the canceller could not be created.
00108 */
00109 modem_echo_can_state_t *modem_echo_can_create(int len);
00110 
00111 /*! Free a modem echo canceller context.
00112     \param ec The echo canceller context.
00113 */
00114 void modem_echo_can_free(modem_echo_can_state_t *ec);
00115 
00116 /*! Flush (reinitialise) a modem echo canceller context.
00117     \param ec The echo canceller context.
00118 */
00119 void modem_echo_can_flush(modem_echo_can_state_t *ec);
00120 
00121 /*! Set the adaption mode of a modem echo canceller context.
00122     \param ec The echo canceller context.
00123     \param adapt The mode.
00124 */
00125 void modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt);
00126 
00127 /*! Process a sample through a modem echo canceller.
00128     \param ec The echo canceller context.
00129     \param tx The transmitted audio sample.
00130     \param rx The received audio sample.
00131     eturn The clean (echo cancelled) received sample.
00132 */
00133 int16_t modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx);
00134 
00135 #endif
00136 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1