00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * modem_connect_tones.c - Generation and detection of tones 00005 * associated with modems calling and answering calls. 00006 * 00007 * Written by Steve Underwood <steveu@coppice.org> 00008 * 00009 * Copyright (C) 2006 Steve Underwood 00010 * 00011 * All rights reserved. 00012 * 00013 * This program is free software; you can redistribute it and/or modify 00014 * it under the terms of the GNU Lesser General Public License version 2.1, 00015 * as published by the Free Software Foundation. 00016 * 00017 * This program is distributed in the hope that it will be useful, 00018 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00019 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00020 * GNU Lesser General Public License for more details. 00021 * 00022 * You should have received a copy of the GNU Lesser General Public 00023 * License along with this program; if not, write to the Free Software 00024 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00025 * 00026 * $Id: modem_connect_tones.h,v 1.18 2008/08/10 03:42:38 steveu Exp $ 00027 */ 00028 00029 /*! \file */ 00030 00031 #if !defined(_SPANDSP_MODEM_CONNECT_TONES_H_) 00032 #define _SPANDSP_MODEM_CONNECT_TONES_H_ 00033 00034 /*! \page modem_connect_tones_page Modem connect tone detection 00035 00036 \section modem_connect_tones_page_sec_1 What does it do? 00037 Some telephony terminal equipment, such as modems, require a channel which is as 00038 clear as possible. They use their own echo cancellation. If the network is also 00039 performing echo cancellation the two cancellors can end up squabbling about the 00040 nature of the channel, with bad results. A special tone is defined which should 00041 cause the network to disable any echo cancellation processes. This is the echo 00042 canceller disable tone. 00043 00044 The tone detector's design assumes the channel is free of any DC component. 00045 00046 \section modem_connect_tones_page_sec_2 How does it work? 00047 A sharp notch filter is implemented as a single bi-quad section. The presence of 00048 the 2100Hz disable tone is detected by comparing the notched filtered energy 00049 with the unfiltered energy. If the notch filtered energy is much lower than the 00050 unfiltered energy, then a large proportion of the energy must be at the notch 00051 frequency. This type of detector may seem less intuitive than using a narrow 00052 bandpass filter to isolate the energy at the notch freqency. However, a sharp 00053 bandpass implemented as an IIR filter rings badly. The reciprocal notch filter 00054 is very well behaved for our purpose. 00055 */ 00056 00057 enum 00058 { 00059 /*! \brief This is reported when a tone stops. */ 00060 MODEM_CONNECT_TONES_NONE = 0, 00061 /*! \brief CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The 00062 bursts repeat for as long as is required. */ 00063 MODEM_CONNECT_TONES_FAX_CNG = 1, 00064 /*! \brief ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s. */ 00065 MODEM_CONNECT_TONES_ANS = 2, 00066 /*! \brief ANS with phase reversals tone is a 2100Hz+-15Hz tone for 3.3s+-0.7s, with a 180 degree 00067 phase jump every 450ms+-25ms. */ 00068 MODEM_CONNECT_TONES_ANS_PR = 3, 00069 /*! \brief The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V.8 */ 00070 MODEM_CONNECT_TONES_ANSAM = 4, 00071 /*! \brief The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM 00072 modulation, as per V.8 */ 00073 MODEM_CONNECT_TONES_ANSAM_PR = 5, 00074 /*! \brief FAX preamble in a string of V.21 HDLC flag octets. This is only valid as a result of tone 00075 detection. It should not be specified as a tone type to transmit or receive. */ 00076 MODEM_CONNECT_TONES_FAX_PREAMBLE = 6, 00077 /*! \brief CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets. 00078 This is only valid as a tone type to receive. It is never reported as a detected tone 00079 type. The report will either be for FAX preamble or CED/ANS tone. */ 00080 MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE = 7 00081 }; 00082 00083 /*! \brief FAX CED tone is the same as ANS tone. */ 00084 #define MODEM_CONNECT_TONES_FAX_CED MODEM_CONNECT_TONES_ANS 00085 00086 /*! 00087 Modem connect tones generator descriptor. This defines the state 00088 of a single working instance of the tone generator. 00089 */ 00090 typedef struct 00091 { 00092 int tone_type; 00093 00094 int32_t tone_phase_rate; 00095 uint32_t tone_phase; 00096 int level; 00097 /*! \brief Countdown to the next phase hop */ 00098 int hop_timer; 00099 /*! \brief Maximum duration timer */ 00100 int duration_timer; 00101 uint32_t mod_phase; 00102 int32_t mod_phase_rate; 00103 int mod_level; 00104 } modem_connect_tones_tx_state_t; 00105 00106 /*! 00107 Modem connect tones receiver descriptor. This defines the state 00108 of a single working instance of the tone detector. 00109 */ 00110 typedef struct 00111 { 00112 /*! \brief The tone type being detected. */ 00113 int tone_type; 00114 /*! \brief Callback routine, using to report detection of the tone. */ 00115 tone_report_func_t tone_callback; 00116 /*! \brief An opaque pointer passed to tone_callback. */ 00117 void *callback_data; 00118 00119 /*! \brief The notch filter state. */ 00120 float z1; 00121 float z2; 00122 /*! \brief The in notch power estimate */ 00123 int notch_level; 00124 /*! \brief The total channel power estimate */ 00125 int channel_level; 00126 /*! \brief Sample counter for the small chunks of samples, after which a test is conducted. */ 00127 int chunk_remainder; 00128 /*! \brief TRUE is the tone is currently confirmed present in the audio. */ 00129 int tone_present; 00130 /*! \brief */ 00131 int tone_on; 00132 /*! \brief A millisecond counter, to time the duration of tone sections. */ 00133 int tone_cycle_duration; 00134 /*! \brief A count of the number of good cycles of tone reversal seen. */ 00135 int good_cycles; 00136 /*! \brief TRUE if the tone has been seen since the last time the user tested for it */ 00137 int hit; 00138 /*! \brief A V.21 FSK modem context used when searching for FAX preamble. */ 00139 fsk_rx_state_t v21rx; 00140 /*! \brief The raw (stuffed) bit stream buffer. */ 00141 unsigned int raw_bit_stream; 00142 /*! \brief The current number of bits in the octet in progress. */ 00143 int num_bits; 00144 /*! \brief Number of consecutive flags seen so far. */ 00145 int flags_seen; 00146 /*! \brief TRUE if framing OK has been announced. */ 00147 int framing_ok_announced; 00148 } modem_connect_tones_rx_state_t; 00149 00150 #if defined(__cplusplus) 00151 extern "C" 00152 { 00153 #endif 00154 00155 /*! \brief Initialise an instance of the modem connect tones generator. 00156 \param s The context. 00157 */ 00158 modem_connect_tones_tx_state_t *modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s, 00159 int tone_type); 00160 00161 /*! \brief Free an instance of the modem connect tones generator. 00162 \param s The context. 00163 \return 0 for OK, else -1. 00164 */ 00165 int modem_connect_tones_tx_free(modem_connect_tones_tx_state_t *s); 00166 00167 /*! \brief Generate a block of modem connect tones samples. 00168 \param s The context. 00169 \param amp An array of signal samples. 00170 \param len The number of samples to generate. 00171 \return The number of samples generated. 00172 */ 00173 int modem_connect_tones_tx(modem_connect_tones_tx_state_t *s, 00174 int16_t amp[], 00175 int len); 00176 00177 /*! \brief Process a block of samples through an instance of the modem connect 00178 tones detector. 00179 \param s The context. 00180 \param amp An array of signal samples. 00181 \param len The number of samples in the array. 00182 \return The number of unprocessed samples. 00183 */ 00184 int modem_connect_tones_rx(modem_connect_tones_rx_state_t *s, 00185 const int16_t amp[], 00186 int len); 00187 00188 /*! \brief Test if a modem_connect tone has been detected. 00189 \param s The context. 00190 \return TRUE if tone is detected, else FALSE. 00191 */ 00192 int modem_connect_tones_rx_get(modem_connect_tones_rx_state_t *s); 00193 00194 /*! \brief Initialise an instance of the modem connect tones detector. 00195 \param s The context. 00196 \param tone_type The type of connect tone being tested for. 00197 \param tone_callback An optional callback routine, used to report tones 00198 \param user_data An opaque pointer passed to the callback routine, 00199 \return A pointer to the context. 00200 */ 00201 modem_connect_tones_rx_state_t *modem_connect_tones_rx_init(modem_connect_tones_rx_state_t *s, 00202 int tone_type, 00203 tone_report_func_t tone_callback, 00204 void *user_data); 00205 00206 /*! \brief Free an instance of the modem connect tones detector. 00207 \param s The context. 00208 \return 0 for OK, else -1. */ 00209 int modem_connect_tones_rx_free(modem_connect_tones_rx_state_t *s); 00210 00211 const char *modem_connect_tone_to_str(int tone); 00212 00213 #if defined(__cplusplus) 00214 } 00215 #endif 00216 00217 #endif 00218 /*- End of file ------------------------------------------------------------*/