sig_tone.h

Go to the documentation of this file.
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 ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1