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 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 ------------------------------------------------------------*/

Generated on Tue Jul 24 11:29:28 2007 for libspandsp by  doxygen 1.5.2