|
5
|
1 /*
|
|
|
2 * SpanDSP - a series of DSP components for telephony
|
|
|
3 *
|
|
|
4 * modem_echo.h - An echo cancellor, suitable for electrical echos in GSTN modems
|
|
|
5 *
|
|
|
6 * Written by Steve Underwood <steveu@coppice.org>
|
|
|
7 *
|
|
|
8 * Copyright (C) 2001, 2004 Steve Underwood
|
|
|
9 *
|
|
|
10 * Based on a bit from here, a bit from there, eye of toad,
|
|
|
11 * ear of bat, etc - plus, of course, my own 2 cents.
|
|
|
12 *
|
|
|
13 * All rights reserved.
|
|
|
14 *
|
|
|
15 * This program is free software; you can redistribute it and/or modify
|
|
|
16 * it under the terms of the GNU General Public License version 2, as
|
|
|
17 * published by the Free Software Foundation.
|
|
|
18 *
|
|
|
19 * This program is distributed in the hope that it will be useful,
|
|
|
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
22 * GNU General Public License for more details.
|
|
|
23 *
|
|
|
24 * You should have received a copy of the GNU General Public License
|
|
|
25 * along with this program; if not, write to the Free Software
|
|
|
26 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
27 *
|
|
|
28 * $Id: modem_echo.h,v 1.7 2006/10/24 13:45:28 steveu Exp $
|
|
|
29 */
|
|
|
30
|
|
|
31 /*! \file */
|
|
|
32
|
|
|
33 #if !defined(_MODEM_ECHO_H_)
|
|
|
34 #define _MODEM_ECHO_H_
|
|
|
35
|
|
|
36 /*! \page modem_echo_can_page Line echo cancellation for modems
|
|
|
37
|
|
|
38 \section modem_echo_can_page_sec_1 What does it do?
|
|
|
39 This module aims to cancel electrical echoes (e.g. from 2-4 wire hybrids)
|
|
|
40 in modem applications. It is not very suitable for speech applications, which
|
|
|
41 require additional refinements for satisfactory performance. It is, however, more
|
|
|
42 efficient and better suited to modem applications.
|
|
|
43
|
|
|
44 \section modem_echo_can_page_sec_2 How does it work?
|
|
|
45 The heart of the echo cancellor is an adaptive FIR filter. This is adapted to
|
|
|
46 match the impulse response of the environment being cancelled. It must be long
|
|
|
47 enough to adequately cover the duration of that impulse response. The signal
|
|
|
48 being transmitted into the environment being cancelled is passed through the
|
|
|
49 FIR filter. The resulting output is an estimate of the echo signal. This is
|
|
|
50 then subtracted from the received signal, and the result should be an estimate
|
|
|
51 of the signal which originates within the environment being cancelled (people
|
|
|
52 talking in the room, or the signal from the far end of a telephone line) free
|
|
|
53 from the echos of our own transmitted signal.
|
|
|
54
|
|
|
55 The FIR filter is adapted using the least mean squares (LMS) algorithm. This
|
|
|
56 algorithm is attributed to Widrow and Hoff, and was introduced in 1960. It is
|
|
|
57 the commonest form of filter adaption used in things like modem line equalisers
|
|
|
58 and line echo cancellers. It works very well if the signal level is constant,
|
|
|
59 which is true for a modem signal. To ensure good performa certain conditions must
|
|
|
60 be met:
|
|
|
61
|
|
|
62 - The transmitted signal has weak self-correlation.
|
|
|
63 - There is no signal being generated within the environment being cancelled.
|
|
|
64
|
|
|
65 The difficulty is that neither of these can be guaranteed. If the adaption is
|
|
|
66 performed while transmitting noise (or something fairly noise like, such as
|
|
|
67 voice) the adaption works very well. If the adaption is performed while
|
|
|
68 transmitting something highly correlative (e.g. tones, like DTMF), the adaption
|
|
|
69 can go seriously wrong. The reason is there is only one solution for the
|
|
|
70 adaption on a near random signal. For a repetitive signal, there are a number of
|
|
|
71 solutions which converge the adaption, and nothing guides the adaption to choose
|
|
|
72 the correct one.
|
|
|
73
|
|
|
74 \section modem_echo_can_page_sec_3 How do I use it?
|
|
|
75 The echo cancellor processes both the transmit and receive streams sample by
|
|
|
76 sample. The processing function is not declared inline. Unfortunately,
|
|
|
77 cancellation requires many operations per sample, so the call overhead is only a
|
|
|
78 minor burden.
|
|
|
79 */
|
|
|
80
|
|
|
81 #include "fir.h"
|
|
|
82
|
|
|
83 /*!
|
|
|
84 Modem line echo canceller descriptor. This defines the working state for a line
|
|
|
85 echo canceller.
|
|
|
86 */
|
|
|
87 typedef struct
|
|
|
88 {
|
|
|
89 int adapt;
|
|
|
90 int taps;
|
|
|
91
|
|
|
92 fir16_state_t fir_state;
|
|
|
93 /*! Echo FIR taps (16 bit version) */
|
|
|
94 int16_t *fir_taps16;
|
|
|
95 /*! Echo FIR taps (32 bit version) */
|
|
|
96 int32_t *fir_taps32;
|
|
|
97
|
|
|
98 int tx_power;
|
|
|
99 int rx_power;
|
|
|
100
|
|
|
101 int curr_pos;
|
|
|
102 } modem_echo_can_state_t;
|
|
|
103
|
|
|
104 /*! Create a modem echo canceller context.
|
|
|
105 \param len The length of the canceller, in samples.
|
|
|
106 eturn The new canceller context, or NULL if the canceller could not be created.
|
|
|
107 */
|
|
|
108 modem_echo_can_state_t *modem_echo_can_create(int len);
|
|
|
109
|
|
|
110 /*! Free a modem echo canceller context.
|
|
|
111 \param ec The echo canceller context.
|
|
|
112 */
|
|
|
113 void modem_echo_can_free(modem_echo_can_state_t *ec);
|
|
|
114
|
|
|
115 /*! Flush (reinitialise) a modem echo canceller context.
|
|
|
116 \param ec The echo canceller context.
|
|
|
117 */
|
|
|
118 void modem_echo_can_flush(modem_echo_can_state_t *ec);
|
|
|
119
|
|
|
120 /*! Set the adaption mode of a modem echo canceller context.
|
|
|
121 \param ec The echo canceller context.
|
|
|
122 \param adapt The mode.
|
|
|
123 */
|
|
|
124 void modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt);
|
|
|
125
|
|
|
126 /*! Process a sample through a modem echo canceller.
|
|
|
127 \param ec The echo canceller context.
|
|
|
128 \param tx The transmitted audio sample.
|
|
|
129 \param rx The received audio sample.
|
|
|
130 eturn The clean (echo cancelled) received sample.
|
|
|
131 */
|
|
|
132 int16_t modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx);
|
|
|
133
|
|
|
134 #endif
|
|
|
135 /*- End of file ------------------------------------------------------------*/
|
