00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * super_tone_rx.h - Flexible telephony supervisory tone detection. 00005 * 00006 * Written by Steve Underwood <steveu@coppice.org> 00007 * 00008 * Copyright (C) 2005 Steve Underwood 00009 * 00010 * All rights reserved. 00011 * 00012 * This program is free software; you can redistribute it and/or modify 00013 * it under the terms of the GNU General Public License version 2, as 00014 * published by the Free Software Foundation. 00015 * 00016 * This program is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 * GNU General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU General Public License 00022 * along with this program; if not, write to the Free Software 00023 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00024 * 00025 * $Id$ 00026 */ 00027 00028 #if !defined(_SPANDSP_SUPER_TONE_RX_H_x) 00029 #define _SPANDSP_SUPER_TONE_RX_H_x 00030 00031 /*! \page super_tone_rx_page Supervisory tone detection 00032 00033 \section super_tone_rx_page_sec_1 What does it do? 00034 00035 The supervisory tone detector may be configured to detect most of the world's 00036 telephone supervisory tones - things like ringback, busy, number unobtainable, 00037 and so on. 00038 00039 The detector aims to meet the need of the standard call progress tones, to 00040 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones, 00041 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special 00042 ringback tone, intercept tone, call waiting tone, busy verification tone, 00043 executive override tone, confirmation tone). 00044 00045 \section super_tone_rx_page_sec_2 How does it work? 00046 00047 The input signal is complex filtered with a bandpass filter that removes DC and 00048 anything above about 800Hz, and the resulting complex signal is decimated by a 00049 factor of 10. This leaves an alias free band of 0 to 800Hz. 00050 00051 A set of periodgrams are calculated, one for each of the frequencies of interest. 00052 A Hamming window is applied to the coefficients used for this, to clean up the 00053 spectral response. The expected phasor rotation between successive periodogram 00054 results is compared with the actual rotation, to evaluate the deviation of the 00055 signal from the expected frequency. 00056 ?????????? 00057 00058 */ 00059 00060 /* The maximum number of frequencies to be monitored */ 00061 #define SUPER_TONE_MAX_FREQS 8 00062 00063 /* Bandpass filtering */ 00064 #define SUPER_TONE_BP_FIR_LEN 60 00065 #define SUPER_TONE_DECIMATION_FACTOR 10 00066 #define SUPER_TONE_FRAME_LEN (4*SUPER_TONE_DECIMATION_FACTOR) 00067 #define SUPER_TONE_BP_SLEN (SUPER_TONE_BP_FIR_LEN - SUPER_TONE_DECIMATION_FACTOR) 00068 #define SUPER_TONE_BP_ALEN (SUPER_TONE_BP_SLEN + SUPER_TONE_FRAME_LEN) 00069 00070 /* Periodogram analysis */ 00071 #define SUPER_TONE_PG_WINDOW 56 00072 00073 /* Energy history period */ 00074 #define SUPER_TONE_ENERGY_SIZE 9 00075 00076 /*! Tone detection indication callback routine */ 00077 //typedef void (*tone_report_func_t)(void *user_data, int code, int level, int delay); 00078 00079 /* Statistics */ 00080 typedef struct 00081 { 00082 /*! Tone power, in dBm0 */ 00083 float power[2]; 00084 /*! Frequency error, in Hz */ 00085 float freq_error[2]; 00086 } supervisory_stats_t; 00087 00088 typedef struct 00089 { 00090 /*! Minimum surge in signal power for a potential tone onset to be declared, in dB. */ 00091 float onset_power_surge; 00092 /*! Minimum acceptable level for a tone's power, in dBm0. */ 00093 float min_energy_threshold; 00094 /*! Maximum permitted variation of a tone's power from its mean level, in dB. */ 00095 float max_energy_variation; 00096 /*! Maximum permitted normal or reverse twist during the onset phase, in dB. */ 00097 float onset_max_twist; 00098 /*! Maximum permitted normal or reverse twist, in dB. */ 00099 float max_twist; 00100 /*! How much energies must be above other components during the onset phase, in dB. */ 00101 float onset_energy_margin; 00102 /*! How much valid energies must be above other components, in dB. */ 00103 float energy_margin; 00104 /*! The maximum permissible frequency offset from the target, in Hz. */ 00105 float max_freq_error; 00106 /*! Length of the onset period, in frames. */ 00107 int onset_frame_count; 00108 /*! Length of the proving period, in frames. */ 00109 int proving_frame_count; 00110 /*! Number of low-energy frames before tone off is declared. */ 00111 int tone_off_frame_count; 00112 /*! Number of inconsistent frames before tone abort is declared */ 00113 int abort_frame_count; 00114 /*! The number of frequencies to be monitored */ 00115 int frequencies; 00116 /*! Periodogram coefficient sets */ 00117 complexf_t pg_coeffs[SUPER_TONE_MAX_FREQS][SUPER_TONE_PG_WINDOW/2]; 00118 /*! Periodogram frame to frame phase offset */ 00119 complexf_t pg_phase_offset[SUPER_TONE_MAX_FREQS]; 00120 /*! Periodogram phase offset scaling. */ 00121 float pg_scale; 00122 } supervisory_rx_desc_t; 00123 00124 typedef struct 00125 { 00126 tone_report_func_t tone_callback; 00127 void *callback_data; 00128 /*! The descriptor for the tone detector. */ 00129 const supervisory_rx_desc_t *desc; 00130 00131 /*! The number of samples in the input signal buffer. */ 00132 int input_signal_len; 00133 /*! Input signal buffer, used to gather enough for a burst of processing. */ 00134 float input_signal[SUPER_TONE_BP_ALEN]; 00135 /*! The decimated signal. */ 00136 complexf_t decimated[SUPER_TONE_PG_WINDOW]; 00137 00138 /*! The energy level out of the bandpass filter, in dBm0 */ 00139 float bandpass_power_db; 00140 00141 /*! The periodogram result at each of the frequencies being monitored */ 00142 complexf_t pg_result[SUPER_TONE_MAX_FREQS]; 00143 /*! The power level at each of the frequencies being monitored */ 00144 float power[SUPER_TONE_MAX_FREQS]; 00145 /*! The previous periodogram result at each of the frequencies being monitored */ 00146 complexf_t last_pg_result[SUPER_TONE_MAX_FREQS]; 00147 supervisory_stats_t stats; 00148 00149 /*! A list of the last few total powers for the 2 main responses */ 00150 float total_tone_power_db_history[SUPER_TONE_ENERGY_SIZE]; 00151 /*! A amoothed version of the total power for the 2 main responses */ 00152 float smoothed_total_tone_power_db; 00153 00154 /*! The indexes into the monitored frequency list of the two strongest 00155 responses (lower frequency first) and the third strongest response. */ 00156 int index[3]; 00157 /*! The energy levels of the two strongest responses (lower frequency first) 00158 and the third strongest response, in dBm0. */ 00159 float power_db[3]; 00160 /*! The frequency error of the two strongest responses (lower frequency first), in Hz */ 00161 float freq_error[2]; 00162 00163 /*! The current state of the detector. */ 00164 int state; 00165 /*! The tones which are considered to be present. */ 00166 int tones_present; 00167 /*! A counter used for the persistence checking of signal changes. */ 00168 int frame_count; 00169 /*! Time, in samples, since the last tone report. */ 00170 int since_last_report; 00171 } supervisory_rx_state_t; 00172 00173 #if defined(__cplusplus) 00174 extern "C" 00175 { 00176 #endif 00177 00178 int supervisory_rx(supervisory_rx_state_t *s, const int16_t amp[], int len); 00179 00180 supervisory_rx_desc_t *supervisory_rx_desc(supervisory_rx_desc_t *conf, 00181 const float freq_list[]); 00182 00183 supervisory_stats_t supervisory_rx_get_stats(supervisory_rx_state_t *s); 00184 00185 supervisory_rx_state_t *supervisory_rx_init(supervisory_rx_state_t *s, 00186 const supervisory_rx_desc_t *conf, 00187 tone_report_func_t callback, 00188 void *user_data); 00189 00190 #if defined(__cplusplus) 00191 } 00192 #endif 00193 00194 #endif 00195 /*- End of file ------------------------------------------------------------*/