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