private/sig_tone.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * private/sig_tone.h - Signalling tone processing for the 2280Hz, 2400Hz, 2600Hz
00005  *                      and similar signalling tones 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 Lesser General Public License version 2.1,
00015  * as 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 Lesser General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU Lesser General Public
00023  * License along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  */
00026 
00027 #if !defined(_SPANDSP_PRIVATE_SIG_TONE_H_)
00028 #define _SPANDSP_PRIVATE_SIG_TONE_H_
00029 
00030 /*! \brief The coefficient set for a pair of cascaded bi-quads that make a signalling notch filter. */
00031 typedef struct
00032 {
00033 #if defined(SPANDSP_USE_FIXED_POINT)
00034     int16_t a1[3];
00035     int16_t b1[3];
00036     int16_t a2[3];
00037     int16_t b2[3];
00038     int postscale;
00039 #else
00040     float a1[3];
00041     float b1[3];
00042     float a2[3];
00043     float b2[3];
00044 #endif
00045 } sig_tone_notch_coeffs_t;
00046 
00047 /*! \brief The coefficient set for a bi-quad that makes a signalling flat filter.
00048            Some signalling tone schemes require such a filter, and some don't.
00049            It is termed a flat filter, to distinguish it from the sharp filter,
00050            but obviously it is not actually flat. It is a broad band weighting
00051            filter. */
00052 typedef struct
00053 {
00054 #if defined(SPANDSP_USE_FIXED_POINT)
00055     /*! \brief Flat mode bandpass bi-quad parameters */
00056     int16_t a[3];
00057     /*! \brief Flat mode bandpass bi-quad parameters */
00058     int16_t b[3];
00059     /*! \brief Post filter scaling */
00060     int postscale;
00061 #else
00062     /*! \brief Flat mode bandpass bi-quad parameters */
00063     float a[3];
00064     /*! \brief Flat mode bandpass bi-quad parameters */
00065     float b[3];
00066 #endif
00067 } sig_tone_flat_coeffs_t;
00068 
00069 /*!
00070     signalling tone descriptor. This defines the working state for a
00071     single instance of the transmit and receive sides of a signalling
00072     tone processor.
00073 */
00074 typedef struct
00075 {
00076     /*! \brief The tones used. */
00077     int tone_freq[2];
00078     /*! \brief The high and low tone amplitudes for each of the tones, in dBm0. */
00079     int tone_amp[2][2];
00080 
00081     /*! \brief The delay, in audio samples, before the high level tone drops
00082                to a low level tone. Some signalling protocols require the
00083                signalling tone be started at a high level, to ensure crisp
00084                initial detection at the receiver, but require the tone
00085                amplitude to drop by a number of dBs if it is sustained,
00086                to reduce crosstalk levels. */
00087     int high_low_timeout;
00088 
00089     /*! \brief Some signalling tone detectors use a sharp initial filter,
00090                changing to a broader, flatter, filter after some delay. This
00091                parameter defines the delay. 0 means it never changes. */
00092     int sharp_flat_timeout;
00093 
00094     /*! \brief Parameters to control the behaviour of the notch filter, used
00095                to remove the tone from the voice path in some protocols. The
00096                notch is applied as fast as possible, when the signalling tone
00097                is detected. Its removal is delayed by this timeout, to avoid
00098                clicky noises from repeated switching of the filter on rapid
00099                pulses of signalling tone. */
00100     int notch_lag_time;
00101 
00102     /*! \brief The tone on persistence check, in audio samples. */
00103     int tone_on_check_time;
00104     /*! \brief The tone off persistence check, in audio samples. */
00105     int tone_off_check_time;
00106 
00107     /*! \brief The number of tones used. */
00108     int tones;
00109     /*! \brief The coefficients for the cascaded bi-quads notch filter. */
00110     const sig_tone_notch_coeffs_t *notch[2];
00111     /*! \brief The coefficients for the single bi-quad flat mode filter. */
00112     const sig_tone_flat_coeffs_t *flat;
00113 
00114     /*! \brief Minimum signalling tone to total power ratio, in dB */
00115     int16_t detection_ratio;
00116     /*! \brief Minimum total power for detection in sharp mode, in dB */
00117     int16_t sharp_detection_threshold;
00118     /*! \brief Minimum total power for detection in flat mode, in dB */
00119     int16_t flat_detection_threshold;
00120 } sig_tone_descriptor_t;
00121 
00122 /*!
00123     Signalling tone transmit state
00124  */
00125 struct sig_tone_tx_state_s
00126 {
00127     /*! \brief The callback function used to handle signalling changes. */
00128     tone_report_func_t sig_update;
00129     /*! \brief A user specified opaque pointer passed to the callback function. */
00130     void *user_data;
00131 
00132     /*! \brief Tone descriptor */
00133     const sig_tone_descriptor_t *desc;
00134 
00135     /*! The phase rates for the one or two tones */
00136     int32_t phase_rate[2];
00137     /*! The phase accumulators for the one or two tones */
00138     uint32_t phase_acc[2];
00139 
00140     /*! The scaling values for the one or two tones, and the high and low level of each tone */
00141     int16_t tone_scaling[2][2];
00142     /*! The sample timer, used to switch between the high and low level tones. */
00143     int high_low_timer;
00144 
00145     /*! \brief Current transmit tone */
00146     int current_tx_tone;
00147     /*! \brief Current transmit timeout */
00148     int current_tx_timeout;
00149     /*! \brief Time in current signalling state, in samples. */
00150     int signalling_state_duration;
00151 };
00152 
00153 /*!
00154     Signalling tone receive state
00155  */
00156 struct sig_tone_rx_state_s
00157 {
00158     /*! \brief The callback function used to handle signalling changes. */
00159     tone_report_func_t sig_update;
00160     /*! \brief A user specified opaque pointer passed to the callback function. */
00161     void *user_data;
00162 
00163     /*! \brief Tone descriptor */
00164     const sig_tone_descriptor_t *desc;
00165 
00166     /*! \brief The current receive tone */
00167     int current_rx_tone;
00168     /*! \brief The timeout for switching from the high level to low level tone detector. */
00169     int high_low_timer;
00170     /*! \brief ??? */
00171     int current_notch_filter;
00172 
00173     struct
00174     {
00175 #if defined(SPANDSP_USE_FIXED_POINT)
00176         /*! \brief The z's for the notch filter */
00177         int16_t notch_z1[2];
00178         /*! \brief The z's for the notch filter */
00179         int16_t notch_z2[2];
00180 #else
00181         /*! \brief The z's for the notch filter */
00182         float notch_z1[2];
00183         /*! \brief The z's for the notch filter */
00184         float notch_z2[2];
00185 #endif
00186 
00187         /*! \brief The power output of the notch. */
00188         power_meter_t power;
00189     } tone[3];
00190 
00191 #if defined(SPANDSP_USE_FIXED_POINT)
00192     /*! \brief The z's for the weighting/bandpass filter. */
00193     int16_t flat_z[2];
00194 #else
00195     /*! \brief The z's for the weighting/bandpass filter. */
00196     float flat_z[2];
00197 #endif
00198     /*! \brief The output power of the flat (unfiltered or flat filtered) path. */
00199     power_meter_t flat_power;
00200 
00201     /*! \brief Persistence check for tone present */
00202     int tone_persistence_timeout;
00203     /*! \brief The tone pattern on the last audio sample */
00204     int last_sample_tone_present;
00205 
00206     /*! \brief The minimum reading from the power meter for detection in flat mode */
00207     int32_t flat_detection_threshold;
00208     /*! \brief The minimum reading from the power meter for detection in sharp mode */
00209     int32_t sharp_detection_threshold;
00210     /*! \brief The minimum ratio between notched power and total power for detection */
00211     int32_t detection_ratio;
00212 
00213     /*! \brief TRUE if in flat mode. FALSE if in sharp mode. */
00214     int flat_mode;
00215     /*! \brief TRUE if the notch filter is enabled in the media path */
00216     int notch_enabled;
00217     /*! \brief ??? */
00218     int flat_mode_timeout;
00219     /*! \brief ??? */
00220     int notch_insertion_timeout;
00221     
00222     /*! \brief ??? */
00223     int signalling_state;
00224     /*! \brief ??? */
00225     int signalling_state_duration;
00226 };
00227 
00228 #endif
00229 /*- End of file ------------------------------------------------------------*/

Generated on 25 Jan 2012 for spandsp by  doxygen 1.6.1