modem_connect_tones.h
Go to the documentation of this file.
/*
* SpanDSP - a series of DSP components for telephony
*
* modem_connect_tones.c - Generation and detection of tones
* associated with modems calling and
* answering calls.
*
* Written by Steve Underwood <steveu@coppice.org>
*
* Copyright (C) 2006 Steve Underwood
*
* All rights reserved.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License version 2.1,
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this program; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/*! \file */
#if !defined(_SPANDSP_MODEM_CONNECT_TONES_H_)
#define _SPANDSP_MODEM_CONNECT_TONES_H_
/*! \page modem_connect_tones_page Modem connect tone detection
\section modem_connect_tones_page_sec_1 What does it do?
Some telephony terminal equipment, such as modems, require a channel which is as
clear as possible. They use their own echo cancellation. If the network is also
performing echo cancellation the two cancellors can end up squabbling about the
nature of the channel, with bad results. A special tone is defined which should
cause the network to disable any echo cancellation processes. This is the echo
canceller disable tone.
The tone detector's design assumes the channel is free of any DC component.
\section modem_connect_tones_page_sec_2 How does it work?
A sharp notch filter is implemented as a single bi-quad section. The presence of
the 2100Hz disable tone is detected by comparing the notched filtered energy
with the unfiltered energy. If the notch filtered energy is much lower than the
unfiltered energy, then a large proportion of the energy must be at the notch
frequency. This type of detector may seem less intuitive than using a narrow
bandpass filter to isolate the energy at the notch freqency. However, a sharp
bandpass implemented as an IIR filter rings badly. The reciprocal notch filter
is very well behaved for our purpose.
*/
enum
{
/*! \brief This is reported when a tone stops. */
MODEM_CONNECT_TONES_NONE = 0,
/*! \brief CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The
bursts repeat for as long as is required. */
MODEM_CONNECT_TONES_FAX_CNG = 1,
/*! \brief ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s. */
MODEM_CONNECT_TONES_ANS = 2,
/*! \brief ANS with phase reversals tone is a 2100Hz+-15Hz tone for 3.3s+-0.7s, with a 180 degree
phase jump every 450ms+-25ms. */
MODEM_CONNECT_TONES_ANS_PR = 3,
/*! \brief The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V.8 */
MODEM_CONNECT_TONES_ANSAM = 4,
/*! \brief The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM
modulation, as per V.8 */
MODEM_CONNECT_TONES_ANSAM_PR = 5,
/*! \brief FAX preamble in a string of V.21 HDLC flag octets. */
MODEM_CONNECT_TONES_FAX_PREAMBLE = 6,
/*! \brief 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. */
MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE = 7,
/*! \brief Bell ANS tone is a pure continuous 2225Hz+-15Hz tone for 3.3s+-0.7s. */
MODEM_CONNECT_TONES_BELL_ANS = 8,
/*! \brief Calling tone is a pure 1300Hz tone, in 0.6s bursts, with 2s silences in between. The
bursts repeat for as long as is required. */
MODEM_CONNECT_TONES_CALLING_TONE = 9
};
/*! \brief FAX CED tone is the same as ANS tone. */
#define MODEM_CONNECT_TONES_FAX_CED MODEM_CONNECT_TONES_ANS
/*!
Modem connect tones generator descriptor. This defines the state
of a single working instance of the tone generator.
*/
typedef struct modem_connect_tones_tx_state_s modem_connect_tones_tx_state_t;
/*!
Modem connect tones receiver descriptor. This defines the state
of a single working instance of the tone detector.
*/
typedef struct modem_connect_tones_rx_state_s modem_connect_tones_rx_state_t;
#if defined(__cplusplus)
extern "C"
{
#endif
/*! \brief Initialise an instance of the modem connect tones generator.
\param s The context.
*/
SPAN_DECLARE(modem_connect_tones_tx_state_t *) modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s,
int tone_type);
/*! \brief Release an instance of the modem connect tones generator.
\param s The context.
\return 0 for OK, else -1.
*/
SPAN_DECLARE(int) modem_connect_tones_tx_release(modem_connect_tones_tx_state_t *s);
/*! \brief Free an instance of the modem connect tones generator.
\param s The context.
\return 0 for OK, else -1.
*/
SPAN_DECLARE(int) modem_connect_tones_tx_free(modem_connect_tones_tx_state_t *s);
/*! \brief Generate a block of modem connect tones samples.
\param s The context.
\param amp An array of signal samples.
\param len The number of samples to generate.
\return The number of samples generated.
*/
SPAN_DECLARE_NONSTD(int) modem_connect_tones_tx(modem_connect_tones_tx_state_t *s,
int16_t amp[],
int len);
/*! \brief Process a block of samples through an instance of the modem connect
tones detector.
\param s The context.
\param amp An array of signal samples.
\param len The number of samples in the array.
\return The number of unprocessed samples.
*/
SPAN_DECLARE_NONSTD(int) modem_connect_tones_rx(modem_connect_tones_rx_state_t *s,
const int16_t amp[],
int len);
/*! \brief Test if a modem_connect tone has been detected.
\param s The context.
\return TRUE if tone is detected, else FALSE.
*/
SPAN_DECLARE(int) modem_connect_tones_rx_get(modem_connect_tones_rx_state_t *s);
/*! \brief Initialise an instance of the modem connect tones detector.
\param s The context.
\param tone_type The type of connect tone being tested for.
\param tone_callback An optional callback routine, used to report tones
\param user_data An opaque pointer passed to the callback routine,
\return A pointer to the context.
*/
SPAN_DECLARE(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);
/*! \brief Release an instance of the modem connect tones detector.
\param s The context.
\return 0 for OK, else -1. */
SPAN_DECLARE(int) modem_connect_tones_rx_release(modem_connect_tones_rx_state_t *s);
/*! \brief Free an instance of the modem connect tones detector.
\param s The context.
\return 0 for OK, else -1. */
SPAN_DECLARE(int) modem_connect_tones_rx_free(modem_connect_tones_rx_state_t *s);
SPAN_DECLARE(const char *) modem_connect_tone_to_str(int tone);
#if defined(__cplusplus)
}
#endif
#endif
/*- End of file ------------------------------------------------------------*/
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(void) async_rx_put_bit(void *user_data
Accept a bit from a received serial bit stream.
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_connect_tones_tx_free
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:357
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_CONNECT_TONES_NONE
@ MODEM_CONNECT_TONES_NONE
This is reported when a tone stops.
Definition modem_connect_tones.h:59
MODEM_CONNECT_TONES_CALLING_TONE
@ MODEM_CONNECT_TONES_CALLING_TONE
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
MODEM_CONNECT_TONES_BELL_ANS
@ MODEM_CONNECT_TONES_BELL_ANS
Bell ANS tone is a pure continuous 2225Hz+-15Hz tone for 3.3s+-0.7s.
Definition modem_connect_tones.h:80
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_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_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
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_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_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_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_connect_tones_tx_state_t
struct modem_connect_tones_tx_state_s modem_connect_tones_tx_state_t
Definition modem_connect_tones.h:93
modem_connect_tones_rx_state_t
struct modem_connect_tones_rx_state_s modem_connect_tones_rx_state_t
Definition modem_connect_tones.h:99
modem_connect_tones_tx_release
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:351
modem_connect_tones_rx_free
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:760
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
modem_connect_tones_rx_release
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:754
modem_connect_tones_rx_state_s
Definition private/modem_connect_tones.h:58
modem_connect_tones_rx_state_s::tone_callback
tone_report_func_t tone_callback
Callback routine, using to report detection of the tone.
Definition private/modem_connect_tones.h:62
modem_connect_tones_rx_state_s::tone_type
int tone_type
The tone type being detected.
Definition private/modem_connect_tones.h:60
modem_connect_tones_tx_state_s
Definition private/modem_connect_tones.h:38