spandsp  0.0.6
modem_echo.h
Go to the documentation of this file.
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 Lesser General Public License version 2.1,
17  * as 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 Lesser General Public License for more details.
23  *
24  * You should have received a copy of the GNU Lesser General Public
25  * License along with this program; if not, write to the Free Software
26  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
27  */
28 
29 /*! \file */
30 
31 #if !defined(_SPANDSP_MODEM_ECHO_H_)
32 #define _SPANDSP_MODEM_ECHO_H_
33 
34 /*! \page modem_echo_can_page Line echo cancellation for modems
35 
36 \section modem_echo_can_page_sec_1 What does it do?
37 This module aims to cancel electrical echoes (e.g. from 2-4 wire hybrids)
38 in modem applications. It is not very suitable for speech applications, which
39 require additional refinements for satisfactory performance. It is, however, more
40 efficient and better suited to modem applications.
41 
42 \section modem_echo_can_page_sec_2 How does it work?
43 The heart of the echo cancellor is an adaptive FIR filter. This is adapted to
44 match the impulse response of the environment being cancelled. It must be long
45 enough to adequately cover the duration of that impulse response. The signal
46 being transmitted into the environment being cancelled is passed through the
47 FIR filter. The resulting output is an estimate of the echo signal. This is
48 then subtracted from the received signal, and the result should be an estimate
49 of the signal which originates within the environment being cancelled (people
50 talking in the room, or the signal from the far end of a telephone line) free
51 from the echos of our own transmitted signal.
52 
53 The FIR filter is adapted using the least mean squares (LMS) algorithm. This
54 algorithm is attributed to Widrow and Hoff, and was introduced in 1960. It is
55 the commonest form of filter adaption used in things like modem line equalisers
56 and line echo cancellers. It works very well if the signal level is constant,
57 which is true for a modem signal. To ensure good performa certain conditions must
58 be met:
59 
60  - The transmitted signal has weak self-correlation.
61  - There is no signal being generated within the environment being cancelled.
62 
63 The difficulty is that neither of these can be guaranteed. If the adaption is
64 performed while transmitting noise (or something fairly noise like, such as
65 voice) the adaption works very well. If the adaption is performed while
66 transmitting something highly correlative (e.g. tones, like DTMF), the adaption
67 can go seriously wrong. The reason is there is only one solution for the
68 adaption on a near random signal. For a repetitive signal, there are a number of
69 solutions which converge the adaption, and nothing guides the adaption to choose
70 the correct one.
71 
72 \section modem_echo_can_page_sec_3 How do I use it?
73 The echo cancellor processes both the transmit and receive streams sample by
74 sample. The processing function is not declared inline. Unfortunately,
75 cancellation requires many operations per sample, so the call overhead is only a
76 minor burden.
77 */
78 
79 #include "fir.h"
80 
81 /*!
82  Modem line echo canceller descriptor. This defines the working state for a line
83  echo canceller.
84 */
86 
87 #if defined(__cplusplus)
88 extern "C"
89 {
90 #endif
91 
92 /*! Create a modem echo canceller context.
93  \param len The length of the canceller, in samples.
94  eturn The new canceller context, or NULL if the canceller could not be created.
95 */
96 SPAN_DECLARE(modem_echo_can_state_t *) modem_echo_can_init(int len);
97 
98 /*! Free a modem echo canceller context.
99  \param ec The echo canceller context.
100 */
101 SPAN_DECLARE(void) modem_echo_can_free(modem_echo_can_state_t *ec);
102 
103 /*! Flush (reinitialise) a modem echo canceller context.
104  \param ec The echo canceller context.
105 */
106 SPAN_DECLARE(void) modem_echo_can_flush(modem_echo_can_state_t *ec);
107 
108 /*! Set the adaption mode of a modem echo canceller context.
109  \param ec The echo canceller context.
110  \param adapt The mode.
111 */
112 SPAN_DECLARE(void) modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt);
113 
114 /*! Process a sample through a modem echo canceller.
115  \param ec The echo canceller context.
116  \param tx The transmitted audio sample.
117  \param rx The received audio sample.
118  eturn The clean (echo cancelled) received sample.
119 */
120 SPAN_DECLARE(int16_t) modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx);
121 
122 #if defined(__cplusplus)
123 }
124 #endif
125 
126 #endif
127 /*- End of file ------------------------------------------------------------*/
MODEM_CONNECT_TONES_ANSAM_PR
@ MODEM_CONNECT_TONES_ANSAM_PR
The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM modulation,...
Definition: modem_connect_tones.h:72
modem_echo_can_init
modem_echo_can_state_t * modem_echo_can_init(int len)
Definition: modem_echo.c:65
modem_connect_tones_tx_state_s::hop_timer
int hop_timer
Countdown to the next phase hop.
Definition: private/modem_connect_tones.h:45
modem_echo_can_adaption_mode
void modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt)
Definition: modem_echo.c:110
MODEM_CONNECT_TONES_FAX_CNG
@ MODEM_CONNECT_TONES_FAX_CNG
CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The bursts repeat for as...
Definition: modem_connect_tones.h:62
dds_mod
int16_t dds_mod(uint32_t *phase_acc, int32_t phase_rate, int16_t scale, int32_t phase)
Generate an integer tone sample, with modulation.
Definition: dds_int.c:378
modem_echo_can_free
void modem_echo_can_free(modem_echo_can_state_t *ec)
Definition: modem_echo.c:56
dds_phase_rate
int32_t dds_phase_rate(float frequency)
Find the phase rate value to achieve a particular frequency.
Definition: dds_int.c:316
modem_echo_can_flush
void modem_echo_can_flush(modem_echo_can_state_t *ec)
Definition: modem_echo.c:98
dds_scaling_dbm0
int16_t dds_scaling_dbm0(float level)
Find the scaling factor needed to achieve a specified level in dBm0.
Definition: dds_int.c:328
awgn_state_s
Definition: private/awgn.h:32
modem_echo_can_adaption_mode
void modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt)
Definition: modem_echo.c:110
power_meter_update
int32_t power_meter_update(power_meter_t *s, int16_t amp)
Update a power meter.
Definition: power_meter.c:84
MODEM_CONNECT_TONES_ANSAM
@ MODEM_CONNECT_TONES_ANSAM
The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V....
Definition: modem_connect_tones.h:69
MODEM_CONNECT_TONES_FAX_CED
#define MODEM_CONNECT_TONES_FAX_CED
FAX CED tone is the same as ANS tone.
Definition: modem_connect_tones.h:87
modem_echo_can_state_s::fir_taps32
int32_t * fir_taps32
Definition: private/modem_echo.h:47
modem_connect_tones_rx_state_s::channel_level
int32_t channel_level
The total channel power estimate.
Definition: private/modem_connect_tones.h:75
MODEM_CONNECT_TONES_ANS
@ MODEM_CONNECT_TONES_ANS
ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s.
Definition: modem_connect_tones.h:64
MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE
@ MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE
CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets....
Definition: modem_connect_tones.h:78
modem_echo_can_free
void modem_echo_can_free(modem_echo_can_state_t *ec)
Definition: modem_echo.c:56
power_meter_t
Definition: power_meter.h:48
modem_echo_can_update
int16_t modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx)
Definition: modem_echo.c:116
MODEM_CONNECT_TONES_FAX_PREAMBLE
@ MODEM_CONNECT_TONES_FAX_PREAMBLE
FAX preamble in a string of V.21 HDLC flag octets.
Definition: modem_connect_tones.h:74
MODEM_CONNECT_TONES_NONE
@ MODEM_CONNECT_TONES_NONE
This is reported when a tone stops.
Definition: modem_connect_tones.h:59
modem_echo_can_state_s::fir_taps16
int16_t * fir_taps16
Definition: private/modem_echo.h:45
MODEM_CONNECT_TONES_ANS_PR
@ MODEM_CONNECT_TONES_ANS_PR
ANS with phase reversals tone is a 2100Hz+-15Hz tone for 3.3s+-0.7s, with a 180 degree phase jump eve...
Definition: modem_connect_tones.h:67
modem_echo_can_flush
void modem_echo_can_flush(modem_echo_can_state_t *ec)
Definition: modem_echo.c:98
modem_connect_tones_rx_state_s::notch_level
int32_t notch_level
The in notch power estimate.
Definition: private/modem_connect_tones.h:73
modem_connect_tones_tx_state_s
Definition: private/modem_connect_tones.h:37
bit_operations.h
modem_connect_tones_rx_state_s
Definition: private/modem_connect_tones.h:57
dc_restore.h
modem_connect_tones_tx_init
modem_connect_tones_tx_state_t * modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s, int tone_type)
Initialise an instance of the modem connect tones generator.
Definition: modem_connect_tones.c:253
spandsp-sim.h
fsk_tx_init
fsk_tx_state_t * fsk_tx_init(fsk_tx_state_t *s, const fsk_spec_t *spec, get_bit_func_t get_bit, void *user_data)
Initialise an FSK modem transmit context.
Definition: fsk.c:153
modem_echo.h
modem_connect_tones_rx_get
int modem_connect_tones_rx_get(modem_connect_tones_rx_state_t *s)
Test if a modem_connect tone has been detected.
Definition: modem_connect_tones.c:696
modem_echo_can_init
modem_echo_can_state_t * modem_echo_can_init(int len)
Definition: modem_echo.c:65
fsk_tx_state_s
Definition: private/fsk.h:33
modem_echo.h
modem_connect_tones_rx_init
modem_connect_tones_rx_state_t * modem_connect_tones_rx_init(modem_connect_tones_rx_state_t *s, int tone_type, tone_report_func_t tone_callback, void *user_data)
Initialise an instance of the modem connect tones detector.
Definition: modem_connect_tones.c:706
modem_echo_can_state_s
Definition: private/modem_echo.h:38
power_meter_init
power_meter_t * power_meter_init(power_meter_t *s, int shift)
Initialise a power meter context.
Definition: power_meter.c:50
modem_echo_can_update
int16_t modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx)
Definition: modem_echo.c:116