spandsp  3.0.0
modem_connect_tones.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * modem_connect_tones.c - Generation and detection of tones
5  * associated with modems calling and
6  * answering calls.
7  *
8  * Written by Steve Underwood <steveu@coppice.org>
9  *
10  * Copyright (C) 2006 Steve Underwood
11  *
12  * All rights reserved.
13  *
14  * This program is free software; you can redistribute it and/or modify
15  * it under the terms of the GNU Lesser General Public License version 2.1,
16  * as published by the Free Software Foundation.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU Lesser General Public License for more details.
22  *
23  * You should have received a copy of the GNU Lesser General Public
24  * License along with this program; if not, write to the Free Software
25  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
26  */
27 
28 /*! \file */
29 
30 #if !defined(_SPANDSP_MODEM_CONNECT_TONES_H_)
31 #define _SPANDSP_MODEM_CONNECT_TONES_H_
32 
33 /*! \page modem_connect_tones_page Modem connect tone detection
34 
35 \section modem_connect_tones_page_sec_1 What does it do?
36 Some telephony terminal equipment, such as modems, require a channel which is as
37 clear as possible. They use their own echo cancellation. If the network is also
38 performing echo cancellation the two cancellors can end up squabbling about the
39 nature of the channel, with bad results. A special tone is defined which should
40 cause the network to disable any echo cancellation processes. This is the echo
41 canceller disable tone.
42 
43 The tone detector's design assumes the channel is free of any DC component.
44 
45 \section modem_connect_tones_page_sec_2 How does it work?
46 A sharp notch filter is implemented as a single bi-quad section. The presence of
47 the 2100Hz disable tone is detected by comparing the notched filtered energy
48 with the unfiltered energy. If the notch filtered energy is much lower than the
49 unfiltered energy, then a large proportion of the energy must be at the notch
50 frequency. This type of detector may seem less intuitive than using a narrow
51 bandpass filter to isolate the energy at the notch freqency. However, a sharp
52 bandpass implemented as an IIR filter rings badly. The reciprocal notch filter
53 is very well behaved for our purpose.
54 */
55 
56 enum
57 {
58  /*! \brief This is reported when a tone stops. */
60  /*! \brief CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The
61  bursts repeat for as long as is required. */
63  /*! \brief ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s. */
65  /*! \brief ANS with phase reversals tone is a 2100Hz+-15Hz tone for 3.3s+-0.7s, with a 180 degree
66  phase jump every 450ms+-25ms. */
68  /*! \brief The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V.8 */
70  /*! \brief The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM
71  modulation, as per V.8 */
73  /*! \brief FAX preamble in a string of V.21 HDLC flag octets. */
75  /*! \brief CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets.
76  This is only valid as a tone type to receive. It is never reported as a detected tone
77  type. The report will either be for FAX preamble or CED/ANS tone. */
79  /*! \brief Bell ANS tone is a pure continuous 2225Hz+-15Hz tone for 3.3s+-0.7s. */
81  /*! \brief Calling tone is a pure 1300Hz tone, in 0.6s bursts, with 2s silences in between. The
82  bursts repeat for as long as is required. */
84 
85  /*! \brief A value to OR with the various tone values above, to specify that tone reporting should be
86  real time, as the tone changes (e.g. the 450ms phase reversals in ANSam), which is needed for
87  applications like RFC4733. The default dehaviour is to only report a tone when it is
88  robustly confirmed. */
90 };
91 
92 /*! \brief FAX CED tone is the same as ANS tone. */
93 #define MODEM_CONNECT_TONES_FAX_CED MODEM_CONNECT_TONES_ANS
94 
95 /*!
96  Modem connect tones generator descriptor. This defines the state
97  of a single working instance of the tone generator.
98 */
100 
101 /*!
102  Modem connect tones receiver descriptor. This defines the state
103  of a single working instance of the tone detector.
104 */
106 
107 #if defined(__cplusplus)
108 extern "C"
109 {
110 #endif
111 
112 /*! \brief Initialise an instance of the modem connect tones generator.
113  \param s The context.
114 */
116  int tone_type);
117 
118 /*! \brief Release an instance of the modem connect tones generator.
119  \param s The context.
120  \return 0 for OK, else -1.
121 */
123 
124 /*! \brief Free an instance of the modem connect tones generator.
125  \param s The context.
126  \return 0 for OK, else -1.
127 */
129 
130 /*! \brief Generate a block of modem connect tones samples.
131  \param s The context.
132  \param amp An array of signal samples.
133  \param len The number of samples to generate.
134  \return The number of samples generated.
135 */
137  int16_t amp[],
138  int len);
139 
140 /*! \brief Process a block of samples through an instance of the modem connect
141  tones detector.
142  \param s The context.
143  \param amp An array of signal samples.
144  \param len The number of samples in the array.
145  \return The number of unprocessed samples.
146 */
148  const int16_t amp[],
149  int len);
150 
151 /*! Fake processing of a missing block of received modem connect tone samples
152  (e.g due to packet loss).
153  \brief Fake processing of a missing block of received modem connect tone samples.
154  \param s The context.
155  \param len The number of samples to fake.
156  \return The number of samples unprocessed.
157 */
159 
160 /*! \brief Test if a modem_connect tone has been detected.
161  \param s The context.
162  \return The code for the detected tone.
163 */
165 
166 /*! \brief Initialise an instance of the modem connect tones detector.
167  \param s The context.
168  \param tone_type The type of connect tone being tested for.
169  \param tone_callback An optional callback routine, used to report tones
170  \param user_data An opaque pointer passed to the callback routine,
171  \return A pointer to the context.
172 */
174  int tone_type,
175  span_tone_report_func_t tone_callback,
176  void *user_data);
177 
178 /*! \brief Release an instance of the modem connect tones detector.
179  \param s The context.
180  \return 0 for OK, else -1. */
182 
183 /*! \brief Free an instance of the modem connect tones detector.
184  \param s The context.
185  \return 0 for OK, else -1. */
187 
188 SPAN_DECLARE(const char *) modem_connect_tone_to_str(int tone);
189 
190 #if defined(__cplusplus)
191 }
192 #endif
193 
194 #endif
195 /*- End of file ------------------------------------------------------------*/
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:302
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:813
int modem_connect_tones_rx(modem_connect_tones_rx_state_t *s, const int16_t amp[], int len)
Process a block of samples through an instance of the modem connect tones detector.
Definition: modem_connect_tones.c:521
span_tone_report_func_t tone_callback
Callback routine, using to report detection of the tone.
Definition: private/modem_connect_tones.h:63
A value to OR with the various tone values above, to specify that tone reporting should be real time...
Definition: modem_connect_tones.h:89
int modem_connect_tones_tx(modem_connect_tones_tx_state_t *s, int16_t amp[], int len)
Generate a block of modem connect tones samples.
Definition: modem_connect_tones.c:114
int modem_connect_tones_rx_free(modem_connect_tones_rx_state_t *s)
Free an instance of the modem connect tones detector.
Definition: modem_connect_tones.c:884
This is reported when a tone stops.
Definition: modem_connect_tones.h:59
The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V.8.
Definition: modem_connect_tones.h:69
ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s.
Definition: modem_connect_tones.h:64
int modem_connect_tones_tx_release(modem_connect_tones_tx_state_t *s)
Release an instance of the modem connect tones generator.
Definition: modem_connect_tones.c:406
FAX preamble in a string of V.21 HDLC flag octets.
Definition: modem_connect_tones.h:74
modem_connect_tones_rx_state_t * modem_connect_tones_rx_init(modem_connect_tones_rx_state_t *s, int tone_type, span_tone_report_func_t tone_callback, void *user_data)
Initialise an instance of the modem connect tones detector.
Definition: modem_connect_tones.c:823
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
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
CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets. This is only valid as a tone type to receive. It is never reported as a detected tone type. The report will either be for FAX preamble or CED/ANS tone.
Definition: modem_connect_tones.h:78
Bell ANS tone is a pure continuous 2225Hz+-15Hz tone for 3.3s+-0.7s.
Definition: modem_connect_tones.h:80
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
Definition: private/modem_connect_tones.h:37
Definition: private/modem_connect_tones.h:57
int modem_connect_tones_rx_fillin(modem_connect_tones_rx_state_t *s, int len)
Fake processing of a missing block of received modem connect tone samples.
Definition: modem_connect_tones.c:807
int modem_connect_tones_tx_free(modem_connect_tones_tx_state_t *s)
Free an instance of the modem connect tones generator.
Definition: modem_connect_tones.c:412
int modem_connect_tones_rx_release(modem_connect_tones_rx_state_t *s)
Release an instance of the modem connect tones detector.
Definition: modem_connect_tones.c:878
int tone_type
The tone type being detected.
Definition: private/modem_connect_tones.h:60
Calling tone is a pure 1300Hz tone, in 0.6s bursts, with 2s silences in between. The bursts repeat fo...
Definition: modem_connect_tones.h:83