00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * sig_tone.h - Signalling tone processing for the 2280Hz, 2600Hz and similar 00005 * signalling tone used in older protocols. 00006 * 00007 * Written by Steve Underwood <steveu@coppice.org> 00008 * 00009 * Copyright (C) 2004 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 General Public License version 2, as 00015 * 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 General Public License for more details. 00021 * 00022 * You should have received a copy of the GNU General Public License 00023 * along with this program; if not, write to the Free Software 00024 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00025 * 00026 * $Id: sig_tone.h,v 1.10 2007/04/08 08:16:18 steveu Exp $ 00027 */ 00028 00029 /*! \file */ 00030 00031 /*! \page sig_tone_page The signaling tone processor 00032 \section sig_tone_sec_1 What does it do? 00033 The signaling tone processor handles the 2280Hz, 2400Hz and 2600Hz tones, used 00034 in many analogue signaling procotols, and digital ones derived from them. 00035 00036 \section sig_tone_sec_2 How does it work? 00037 TBD 00038 */ 00039 00040 #if !defined(_SPANDSP_SIG_TONE_H_) 00041 #define _SPANDSP_SIG_TONE_H_ 00042 00043 typedef int (*sig_tone_func_t)(void *user_data, int what); 00044 00045 /* The optional tone sets */ 00046 enum 00047 { 00048 SIG_TONE_2280HZ = 1, 00049 SIG_TONE_2600HZ, 00050 SIG_TONE_2400HZ_2600HZ 00051 }; 00052 00053 #define SIG_TONE_1_PRESENT 0x001 00054 #define SIG_TONE_1_CHANGE 0x002 00055 #define SIG_TONE_2_PRESENT 0x004 00056 #define SIG_TONE_2_CHANGE 0x008 00057 #define SIG_TONE_TX_PASSTHROUGH 0x010 00058 #define SIG_TONE_RX_PASSTHROUGH 0x020 00059 #define SIG_TONE_UPDATE_REQUEST 0x100 00060 00061 /*! 00062 Signaling tone descriptor. This defines the working state for a 00063 single instance of the transmit and receive sides of a signaling 00064 tone processor. 00065 */ 00066 typedef struct 00067 { 00068 /*! \brief The tones used. */ 00069 int tone_freq[2]; 00070 /*! \brief The high and low tone amplitudes. */ 00071 int tone_amp[2]; 00072 00073 /*! \brief The delay, in audio samples, before the high level tone drops 00074 to a low level tone. */ 00075 int high_low_timeout; 00076 00077 /*! \brief Some signaling tone detectors use a sharp initial filter, 00078 changing to a broader band filter after some delay. This 00079 parameter defines the delay. 0 means it never changes. */ 00080 int sharp_flat_timeout; 00081 00082 /*! \brief Parameters to control the behaviour of the notch filter, used 00083 to remove the tone from the voice path in some protocols. */ 00084 int notch_lag_time; 00085 int notch_allowed; 00086 00087 /*! \brief The tone on persistence check, in audio samples. */ 00088 int tone_on_check_time; 00089 /*! \brief The tone off persistence check, in audio samples. */ 00090 int tone_off_check_time; 00091 00092 /*! \brief The coefficients for the cascaded bi-quads notch filter. */ 00093 int32_t notch_a1[3]; 00094 int32_t notch_b1[3]; 00095 int32_t notch_a2[3]; 00096 int32_t notch_b2[3]; 00097 int notch_postscale; 00098 00099 /*! \brief Flat mode bandpass bi-quad parameters */ 00100 int32_t broad_a[3]; 00101 int32_t broad_b[3]; 00102 int broad_postscale; 00103 00104 /*! \brief The coefficients for the post notch leaky integrator. */ 00105 int32_t notch_slugi; 00106 int32_t notch_slugp; 00107 00108 /*! \brief The coefficients for the post modulus leaky integrator in the 00109 unfiltered data path. The prescale value incorporates the 00110 detection ratio. This is called the guard ratio in some 00111 protocols. */ 00112 int32_t unfiltered_slugi; 00113 int32_t unfiltered_slugp; 00114 00115 /*! \brief The coefficients for the post modulus leaky integrator in the 00116 bandpass filter data path. */ 00117 int32_t broad_slugi; 00118 int32_t broad_slugp; 00119 00120 /*! \brief Masks which effectively threshold the notched, weighted and 00121 bandpassed data. */ 00122 int32_t notch_threshold; 00123 int32_t unfiltered_threshold; 00124 int32_t broad_threshold; 00125 } sig_tone_descriptor_t; 00126 00127 typedef struct 00128 { 00129 /*! \brief The callback function used to handle signaling changes. */ 00130 sig_tone_func_t sig_update; 00131 /*! \brief A user specified opaque pointer passed to the callback function. */ 00132 void *user_data; 00133 00134 /*! \brief Transmit side parameters */ 00135 sig_tone_descriptor_t *desc; 00136 int32_t phase_rate[2]; 00137 int32_t tone_scaling[2]; 00138 uint32_t phase_acc[2]; 00139 00140 int high_low_timer; 00141 00142 /*! \brief The z's for the notch filter */ 00143 int32_t notch_z1[3]; 00144 int32_t notch_z2[3]; 00145 00146 /*! \brief The z's for the weighting/bandpass filter. */ 00147 int32_t broad_z[3]; 00148 00149 /*! \brief The z's for the integrators. */ 00150 int32_t notch_zl; 00151 int32_t broad_zl; 00152 00153 /*! \brief The thresholded data. */ 00154 int32_t mown_notch; 00155 int32_t mown_bandpass; 00156 00157 int flat_mode; 00158 int tone_present; 00159 int notch_enabled; 00160 int flat_mode_timeout; 00161 int notch_insertion_timeout; 00162 int tone_persistence_timeout; 00163 00164 int current_tx_tone; 00165 int current_tx_timeout; 00166 int signaling_state_duration; 00167 } sig_tone_state_t; 00168 00169 #if defined(__cplusplus) 00170 extern "C" 00171 { 00172 #endif 00173 00174 /*! Initialise a signaling tone context. 00175 \brief Initialise a signaling tone context. 00176 \param s The signaling tone context. 00177 \param tone_type The type of signaling tone. 00178 \param sig_update Callback function to handle signaling updates. 00179 \param user_data An opaque pointer. 00180 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00181 sig_tone_state_t *sig_tone_init(sig_tone_state_t *s, int tone_type, sig_tone_func_t sig_update, void *user_data); 00182 00183 /*! Process a block of received audio samples. 00184 \brief Process a block of received audio samples. 00185 \param s The signaling tone context. 00186 \param amp The audio sample buffer. 00187 \param len The number of samples in the buffer. 00188 \return The number of samples unprocessed. */ 00189 int sig_tone_rx(sig_tone_state_t *s, int16_t amp[], int len); 00190 00191 /*! Generate a block of signaling tone audio samples. 00192 \brief Generate a block of signaling tone audio samples. 00193 \param s The signaling tone context. 00194 \param amp The audio sample buffer. 00195 \param len The number of samples to be generated. 00196 \return The number of samples actually generated. */ 00197 int sig_tone_tx(sig_tone_state_t *s, int16_t amp[], int len); 00198 00199 #if defined(__cplusplus) 00200 } 00201 #endif 00202 00203 #endif 00204 /*- End of file ------------------------------------------------------------*/