spandsp  3.0.0
private/sig_tone.h
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * private/sig_tone.h - Signalling tone processing for the 2280Hz, 2400Hz, 2600Hz
5  * and similar signalling tones used in older protocols.
6  *
7  * Written by Steve Underwood <steveu@coppice.org>
8  *
9  * Copyright (C) 2004 Steve Underwood
10  *
11  * All rights reserved.
12  *
13  * This program is free software; you can redistribute it and/or modify
14  * it under the terms of the GNU Lesser General Public License version 2.1,
15  * as published by the Free Software Foundation.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  * GNU Lesser General Public License for more details.
21  *
22  * You should have received a copy of the GNU Lesser General Public
23  * License along with this program; if not, write to the Free Software
24  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25  */
26 
27 #if !defined(_SPANDSP_PRIVATE_SIG_TONE_H_)
28 #define _SPANDSP_PRIVATE_SIG_TONE_H_
29 
30 /*! \brief The coefficient set for a pair of cascaded bi-quads that make a signalling notch filter. */
31 typedef struct
32 {
33 #if defined(SPANDSP_USE_FIXED_POINT)
34  int16_t a1[3];
35  int16_t b1[3];
36  int16_t a2[3];
37  int16_t b2[3];
38  int postscale;
39 #else
40  float a1[3];
41  float b1[3];
42  float a2[3];
43  float b2[3];
44 #endif
46 
47 /*! \brief The coefficient set for a bi-quad that makes a signalling flat filter.
48  Some signalling tone schemes require such a filter, and some don't.
49  It is termed a flat filter, to distinguish it from the sharp filter,
50  but obviously it is not actually flat. It is a broad band weighting
51  filter. */
52 typedef struct
53 {
54 #if defined(SPANDSP_USE_FIXED_POINT)
55  /*! \brief Flat mode bandpass bi-quad parameters */
56  int16_t a[3];
57  /*! \brief Flat mode bandpass bi-quad parameters */
58  int16_t b[3];
59  /*! \brief Post filter scaling */
60  int postscale;
61 #else
62  /*! \brief Flat mode bandpass bi-quad parameters */
63  float a[3];
64  /*! \brief Flat mode bandpass bi-quad parameters */
65  float b[3];
66 #endif
68 
69 /*!
70  signalling tone descriptor. This defines the working state for a
71  single instance of the transmit and receive sides of a signalling
72  tone processor.
73 */
74 typedef struct
75 {
76  /*! \brief The tones used. */
77  int tone_freq[2];
78  /*! \brief The high and low tone amplitudes for each of the tones, in dBm0. */
79  int tone_amp[2][2];
80 
81  /*! \brief The delay, in audio samples, before the high level tone drops
82  to a low level tone. Some signalling protocols require the
83  signalling tone be started at a high level, to ensure crisp
84  initial detection at the receiver, but require the tone
85  amplitude to drop by a number of dBs if it is sustained,
86  to reduce crosstalk levels. */
87  span_sample_timer_t high_low_timeout;
88 
89  /*! \brief Some signalling tone detectors use a sharp initial filter,
90  changing to a broader, flatter, filter after some delay. This
91  parameter defines the delay. 0 means it never changes. */
92  span_sample_timer_t sharp_flat_timeout;
93 
94  /*! \brief Parameters to control the behaviour of the notch filter, used
95  to remove the tone from the voice path in some protocols. The
96  notch is applied as fast as possible, when the signalling tone
97  is detected. Its removal is delayed by this timeout, to avoid
98  clicky noises from repeated switching of the filter on rapid
99  pulses of signalling tone. */
100  span_sample_timer_t notch_lag_time;
101 
102  /*! \brief The tone on persistence check, in audio samples. */
103  span_sample_timer_t tone_on_check_time;
104  /*! \brief The tone off persistence check, in audio samples. */
105  span_sample_timer_t tone_off_check_time;
106 
107  /*! \brief The number of tones used. */
108  int tones;
109  /*! \brief The coefficients for the cascaded bi-quads notch filter. */
110  const sig_tone_notch_coeffs_t *notch[2];
111  /*! \brief The coefficients for the single bi-quad flat mode filter. */
113 
114 #if defined(SPANDSP_USE_FIXED_POINT)
115  /*! \brief Minimum signalling tone to total power ratio, in dB */
116  int16_t detection_ratio;
117  /*! \brief Minimum total power for detection in sharp mode, in dB */
118  int16_t sharp_detection_threshold;
119  /*! \brief Minimum total power for detection in flat mode, in dB */
120  int16_t flat_detection_threshold;
121 #else
122  /*! \brief Minimum signalling tone to total power ratio, in dB */
124  /*! \brief Minimum total power for detection in sharp mode, in dB */
126  /*! \brief Minimum total power for detection in flat mode, in dB */
128 #endif
130 
131 /*!
132  Signalling tone transmit state
133  */
135 {
136  /*! \brief The callback function used to handle signalling changes. */
137  span_tone_report_func_t sig_update;
138  /*! \brief A user specified opaque pointer passed to the callback function. */
139  void *user_data;
140 
141  /*! \brief Tone descriptor */
143 
144  /*! The phase rates for the one or two tones */
145  int32_t phase_rate[2];
146  /*! The phase accumulators for the one or two tones */
147  uint32_t phase_acc[2];
148 
149  /*! The scaling values for the one or two tones, and the high and low level of each tone */
150  int16_t tone_scaling[2][2];
151  /*! The sample timer, used to switch between the high and low level tones. */
152  span_sample_timer_t high_low_timer;
153 
154  /*! \brief Current transmit tone */
156  /*! \brief Current transmit timeout. */
157  span_sample_timer_t current_tx_timeout;
158  /*! \brief Time in current signalling state. */
159  span_sample_timer_t signalling_state_duration;
160 };
161 
162 /*!
163  Signalling tone receive state
164  */
166 {
167  /*! \brief The callback function used to handle signalling changes. */
168  span_tone_report_func_t sig_update;
169  /*! \brief A user specified opaque pointer passed to the callback function. */
170  void *user_data;
171 
172  /*! \brief Tone descriptor */
174 
175  /*! \brief The current receive tone */
177  /*! \brief The timeout for switching from the high level to low level tone detector. */
178  span_sample_timer_t high_low_timer;
179  /*! \brief ??? */
181 
182  struct
183  {
184 #if defined(SPANDSP_USE_FIXED_POINT)
185  /*! \brief The z's for the notch filter */
186  int16_t notch_z1[2];
187  /*! \brief The z's for the notch filter */
188  int16_t notch_z2[2];
189 #else
190  /*! \brief The z's for the notch filter */
191  float notch_z1[2];
192  /*! \brief The z's for the notch filter */
193  float notch_z2[2];
194 #endif
195 
196  /*! \brief The power output of the notch. */
198  } tone[3];
199 
200 #if defined(SPANDSP_USE_FIXED_POINT)
201  /*! \brief The z's for the weighting/bandpass filter. */
202  int16_t flat_z[2];
203 #else
204  /*! \brief The z's for the weighting/bandpass filter. */
205  float flat_z[2];
206 #endif
207  /*! \brief The output power of the flat (unfiltered or flat filtered) path. */
209 
210  /*! \brief Persistence check for tone present */
211  span_sample_timer_t tone_persistence_timeout;
212  /*! \brief The tone pattern on the last audio sample */
214 
215  /*! \brief The minimum reading from the power meter for detection in flat mode */
217  /*! \brief The minimum reading from the power meter for detection in sharp mode */
219  /*! \brief The minimum ratio between notched power and total power for detection */
221 
222  /*! \brief True if in flat mode. False if in sharp mode. */
223  bool flat_mode;
224  /*! \brief True if the notch filter is enabled in the media path */
226  /*! \brief ??? */
227  span_sample_timer_t flat_mode_timeout;
228  /*! \brief ??? */
229  span_sample_timer_t notch_insertion_timeout;
230 
231  /*! \brief ??? */
233  /*! \brief ??? */
234  span_sample_timer_t signalling_state_duration;
235 };
236 
237 #endif
238 /*- End of file ------------------------------------------------------------*/
The coefficient set for a pair of cascaded bi-quads that make a signalling notch filter.
Definition: private/sig_tone.h:31
bool notch_enabled
True if the notch filter is enabled in the media path.
Definition: private/sig_tone.h:225
int16_t tone_scaling[2][2]
Definition: private/sig_tone.h:150
span_sample_timer_t signalling_state_duration
???
Definition: private/sig_tone.h:234
Definition: private/power_meter.h:33
power_meter_t power
The power output of the notch.
Definition: private/sig_tone.h:197
span_sample_timer_t notch_insertion_timeout
???
Definition: private/sig_tone.h:229
int32_t detection_ratio
The minimum ratio between notched power and total power for detection.
Definition: private/sig_tone.h:220
const sig_tone_descriptor_t * desc
Tone descriptor.
Definition: private/sig_tone.h:173
span_sample_timer_t current_tx_timeout
Current transmit timeout.
Definition: private/sig_tone.h:157
span_sample_timer_t tone_persistence_timeout
Persistence check for tone present.
Definition: private/sig_tone.h:211
Definition: private/sig_tone.h:134
span_sample_timer_t flat_mode_timeout
???
Definition: private/sig_tone.h:227
span_tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition: private/sig_tone.h:168
const sig_tone_descriptor_t * desc
Tone descriptor.
Definition: private/sig_tone.h:142
float notch_z2[2]
The z&#39;s for the notch filter.
Definition: private/sig_tone.h:193
const sig_tone_flat_coeffs_t * flat
The coefficients for the single bi-quad flat mode filter.
Definition: private/sig_tone.h:112
Definition: private/sig_tone.h:165
span_sample_timer_t high_low_timeout
The delay, in audio samples, before the high level tone drops to a low level tone. Some signalling protocols require the signalling tone be started at a high level, to ensure crisp initial detection at the receiver, but require the tone amplitude to drop by a number of dBs if it is sustained, to reduce crosstalk levels.
Definition: private/sig_tone.h:87
span_sample_timer_t high_low_timer
Definition: private/sig_tone.h:152
uint32_t phase_acc[2]
Definition: private/sig_tone.h:147
int signalling_state
???
Definition: private/sig_tone.h:232
int32_t sharp_detection_threshold
The minimum reading from the power meter for detection in sharp mode.
Definition: private/sig_tone.h:218
span_sample_timer_t tone_off_check_time
The tone off persistence check, in audio samples.
Definition: private/sig_tone.h:105
span_sample_timer_t high_low_timer
The timeout for switching from the high level to low level tone detector.
Definition: private/sig_tone.h:178
float flat_detection_threshold
Minimum total power for detection in flat mode, in dB.
Definition: private/sig_tone.h:127
int32_t phase_rate[2]
Definition: private/sig_tone.h:145
span_tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition: private/sig_tone.h:137
span_sample_timer_t signalling_state_duration
Time in current signalling state.
Definition: private/sig_tone.h:159
bool flat_mode
True if in flat mode. False if in sharp mode.
Definition: private/sig_tone.h:223
void * user_data
A user specified opaque pointer passed to the callback function.
Definition: private/sig_tone.h:170
int tones
The number of tones used.
Definition: private/sig_tone.h:108
Definition: private/sig_tone.h:74
float sharp_detection_threshold
Minimum total power for detection in sharp mode, in dB.
Definition: private/sig_tone.h:125
span_sample_timer_t sharp_flat_timeout
Some signalling tone detectors use a sharp initial filter, changing to a broader, flatter...
Definition: private/sig_tone.h:92
float notch_z1[2]
The z&#39;s for the notch filter.
Definition: private/sig_tone.h:191
float detection_ratio
Minimum signalling tone to total power ratio, in dB.
Definition: private/sig_tone.h:123
span_sample_timer_t notch_lag_time
Parameters to control the behaviour of the notch filter, used to remove the tone from the voice path ...
Definition: private/sig_tone.h:100
void * user_data
A user specified opaque pointer passed to the callback function.
Definition: private/sig_tone.h:139
float flat_z[2]
The z&#39;s for the weighting/bandpass filter.
Definition: private/sig_tone.h:205
int32_t flat_detection_threshold
The minimum reading from the power meter for detection in flat mode.
Definition: private/sig_tone.h:216
int current_notch_filter
???
Definition: private/sig_tone.h:180
power_meter_t flat_power
The output power of the flat (unfiltered or flat filtered) path.
Definition: private/sig_tone.h:208
The coefficient set for a bi-quad that makes a signalling flat filter. Some signalling tone schemes r...
Definition: private/sig_tone.h:52
int current_tx_tone
Current transmit tone.
Definition: private/sig_tone.h:155
int current_rx_tone
The current receive tone.
Definition: private/sig_tone.h:176
span_sample_timer_t tone_on_check_time
The tone on persistence check, in audio samples.
Definition: private/sig_tone.h:103
int last_sample_tone_present
The tone pattern on the last audio sample.
Definition: private/sig_tone.h:213