spandsp  0.0.6
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. */
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. */
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. */
101 
102  /*! \brief The tone on persistence check, in audio samples. */
104  /*! \brief The tone off persistence check, in audio samples. */
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  /*! \brief Minimum signalling tone to total power ratio, in dB */
116  /*! \brief Minimum total power for detection in sharp mode, in dB */
118  /*! \brief Minimum total power for detection in flat mode, in dB */
121 
122 /*!
123  Signalling tone transmit state
124  */
126 {
127  /*! \brief The callback function used to handle signalling changes. */
128  tone_report_func_t sig_update;
129  /*! \brief A user specified opaque pointer passed to the callback function. */
130  void *user_data;
131 
132  /*! \brief Tone descriptor */
134 
135  /*! The phase rates for the one or two tones */
136  int32_t phase_rate[2];
137  /*! The phase accumulators for the one or two tones */
138  uint32_t phase_acc[2];
139 
140  /*! The scaling values for the one or two tones, and the high and low level of each tone */
141  int16_t tone_scaling[2][2];
142  /*! The sample timer, used to switch between the high and low level tones. */
144 
145  /*! \brief Current transmit tone */
147  /*! \brief Current transmit timeout */
149  /*! \brief Time in current signalling state, in samples. */
151 };
152 
153 /*!
154  Signalling tone receive state
155  */
157 {
158  /*! \brief The callback function used to handle signalling changes. */
159  tone_report_func_t sig_update;
160  /*! \brief A user specified opaque pointer passed to the callback function. */
161  void *user_data;
162 
163  /*! \brief Tone descriptor */
165 
166  /*! \brief The current receive tone */
168  /*! \brief The timeout for switching from the high level to low level tone detector. */
170  /*! \brief ??? */
172 
173  struct
174  {
175 #if defined(SPANDSP_USE_FIXED_POINT)
176  /*! \brief The z's for the notch filter */
177  int16_t notch_z1[2];
178  /*! \brief The z's for the notch filter */
179  int16_t notch_z2[2];
180 #else
181  /*! \brief The z's for the notch filter */
182  float notch_z1[2];
183  /*! \brief The z's for the notch filter */
184  float notch_z2[2];
185 #endif
186 
187  /*! \brief The power output of the notch. */
189  } tone[3];
190 
191 #if defined(SPANDSP_USE_FIXED_POINT)
192  /*! \brief The z's for the weighting/bandpass filter. */
193  int16_t flat_z[2];
194 #else
195  /*! \brief The z's for the weighting/bandpass filter. */
196  float flat_z[2];
197 #endif
198  /*! \brief The output power of the flat (unfiltered or flat filtered) path. */
200 
201  /*! \brief Persistence check for tone present */
203  /*! \brief The tone pattern on the last audio sample */
205 
206  /*! \brief The minimum reading from the power meter for detection in flat mode */
208  /*! \brief The minimum reading from the power meter for detection in sharp mode */
210  /*! \brief The minimum ratio between notched power and total power for detection */
212 
213  /*! \brief TRUE if in flat mode. FALSE if in sharp mode. */
215  /*! \brief TRUE if the notch filter is enabled in the media path */
217  /*! \brief ??? */
219  /*! \brief ??? */
221 
222  /*! \brief ??? */
224  /*! \brief ??? */
226 };
227 
228 #endif
229 /*- End of file ------------------------------------------------------------*/
SIG_TONE_2_PRESENT
@ SIG_TONE_2_PRESENT
Definition: sig_tone.h:74
sig_tone_rx_state_s
Definition: private/sig_tone.h:157
sig_tone_tx_state_s::user_data
void * user_data
A user specified opaque pointer passed to the callback function.
Definition: private/sig_tone.h:130
sig_tone_descriptor_t::tone_amp
int tone_amp[2][2]
The high and low tone amplitudes for each of the tones, in dBm0.
Definition: private/sig_tone.h:79
sig_tone_descriptor_t::detection_ratio
int16_t detection_ratio
Minimum signalling tone to total power ratio, in dB.
Definition: private/sig_tone.h:115
sig_tone_rx_state_s::current_rx_tone
int current_rx_tone
The current receive tone.
Definition: private/sig_tone.h:167
sig_tone_flat_coeffs_t::b
float b[3]
Flat mode bandpass bi-quad parameters.
Definition: private/sig_tone.h:65
dds_mod
int16_t dds_mod(uint32_t *phase_acc, int32_t phase_rate, int16_t scale, int32_t phase)
Generate an integer tone sample, with modulation.
Definition: dds_int.c:378
sig_tone_rx_state_s::flat_detection_threshold
int32_t flat_detection_threshold
The minimum reading from the power meter for detection in flat mode.
Definition: private/sig_tone.h:207
sig_tone_rx_release
int sig_tone_rx_release(sig_tone_rx_state_t *s)
Release a signalling tone receiver context.
Definition: sig_tone.c:680
sig_tone_rx_state_s::notch_insertion_timeout
int notch_insertion_timeout
???
Definition: private/sig_tone.h:220
sig_tone_descriptor_t::flat_detection_threshold
int16_t flat_detection_threshold
Minimum total power for detection in flat mode, in dB.
Definition: private/sig_tone.h:119
sig_tone_rx_state_s::flat_power
power_meter_t flat_power
The output power of the flat (unfiltered or flat filtered) path.
Definition: private/sig_tone.h:199
sig_tone_tx_state_s::tone_scaling
int16_t tone_scaling[2][2]
Definition: private/sig_tone.h:141
dds_phase_rate
int32_t dds_phase_rate(float frequency)
Find the phase rate value to achieve a particular frequency.
Definition: dds_int.c:316
sig_tone_descriptor_t::high_low_timeout
int high_low_timeout
The delay, in audio samples, before the high level tone drops to a low level tone....
Definition: private/sig_tone.h:87
sig_tone_rx_set_mode
void sig_tone_rx_set_mode(sig_tone_rx_state_t *s, int mode, int duration)
Set the receive mode.
Definition: sig_tone.c:626
sig_tone_descriptor_t::tones
int tones
The number of tones used.
Definition: private/sig_tone.h:108
dds_scaling_dbm0
int16_t dds_scaling_dbm0(float level)
Find the scaling factor needed to achieve a specified level in dBm0.
Definition: dds_int.c:328
sig_tone_descriptor_t::sharp_detection_threshold
int16_t sharp_detection_threshold
Minimum total power for detection in sharp mode, in dB.
Definition: private/sig_tone.h:117
sig_tone_rx_state_s::current_notch_filter
int current_notch_filter
???
Definition: private/sig_tone.h:171
power_meter_update
int32_t power_meter_update(power_meter_t *s, int16_t amp)
Update a power meter.
Definition: power_meter.c:84
sig_tone_rx_state_s::tone_persistence_timeout
int tone_persistence_timeout
Persistence check for tone present.
Definition: private/sig_tone.h:202
SIG_TONE_RX_FILTER_TONE
@ SIG_TONE_RX_FILTER_TONE
Definition: sig_tone.h:83
sig_tone_rx_state_s::sig_update
tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition: private/sig_tone.h:159
sig_tone_tx_state_s::sig_update
tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition: private/sig_tone.h:128
sig_tone_rx_state_s::desc
const sig_tone_descriptor_t * desc
Tone descriptor.
Definition: private/sig_tone.h:164
sig_tone_descriptor_t::notch_lag_time
int 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
power_meter_t
Definition: power_meter.h:49
complex.h
sig_tone_descriptor_t::flat
const sig_tone_flat_coeffs_t * flat
The coefficients for the single bi-quad flat mode filter.
Definition: private/sig_tone.h:112
sig_tone_tx_state_s::signalling_state_duration
int signalling_state_duration
Time in current signalling state, in samples.
Definition: private/sig_tone.h:150
sig_tone_tx_state_s::desc
const sig_tone_descriptor_t * desc
Tone descriptor.
Definition: private/sig_tone.h:133
sig_tone_tx_state_s::current_tx_tone
int current_tx_tone
Current transmit tone.
Definition: private/sig_tone.h:146
sig_tone_rx_state_s::signalling_state
int signalling_state
???
Definition: private/sig_tone.h:223
sig_tone_tx_set_mode
void sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode, int duration)
Set the tone mode.
Definition: sig_tone.c:299
sig_tone_tx_state_s::phase_acc
uint32_t phase_acc[2]
Definition: private/sig_tone.h:138
sig_tone_flat_coeffs_t::a
float a[3]
Flat mode bandpass bi-quad parameters.
Definition: private/sig_tone.h:63
sig_tone_rx_state_s::sharp_detection_threshold
int32_t sharp_detection_threshold
The minimum reading from the power meter for detection in sharp mode.
Definition: private/sig_tone.h:209
saturated.h
SIG_TONE_TX_UPDATE_REQUEST
@ SIG_TONE_TX_UPDATE_REQUEST
Definition: sig_tone.h:85
sig_tone_tx
int sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len)
Generate a block of signalling tone audio samples.
Definition: sig_tone.c:222
span_sched_state_s
Definition: private/schedule.h:39
sig_tone_notch_coeffs_t
The coefficient set for a pair of cascaded bi-quads that make a signalling notch filter.
Definition: private/sig_tone.h:32
sig_tone.h
sig_tone_tx_init
sig_tone_tx_state_t * sig_tone_tx_init(sig_tone_tx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data)
Initialise a signalling tone context.
Definition: sig_tone.c:319
sig_tone_tx_free
int sig_tone_tx_free(sig_tone_tx_state_t *s)
Free a signalling tone transmitter context.
Definition: sig_tone.c:358
sig_tone_rx_state_s::detection_ratio
int32_t detection_ratio
The minimum ratio between notched power and total power for detection.
Definition: private/sig_tone.h:211
sig_tone_tx_state_s::high_low_timer
int high_low_timer
Definition: private/sig_tone.h:143
sig_tone_rx_state_s::high_low_timer
int high_low_timer
The timeout for switching from the high level to low level tone detector.
Definition: private/sig_tone.h:169
sig_tone_tx_state_s::current_tx_timeout
int current_tx_timeout
Current transmit timeout.
Definition: private/sig_tone.h:148
sig_tone_rx_state_s::user_data
void * user_data
A user specified opaque pointer passed to the callback function.
Definition: private/sig_tone.h:161
sig_tone_rx
int sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len)
Process a block of received audio samples.
Definition: sig_tone.c:368
sig_tone_rx_state_s::flat_z
float flat_z[2]
The z's for the weighting/bandpass filter.
Definition: private/sig_tone.h:196
dc_restore.h
sig_tone_rx_state_s::power
power_meter_t power
The power output of the notch.
Definition: private/sig_tone.h:188
SIG_TONE_2_CHANGE
@ SIG_TONE_2_CHANGE
Definition: sig_tone.h:76
sig_tone_descriptor_t::tone_off_check_time
int tone_off_check_time
The tone off persistence check, in audio samples.
Definition: private/sig_tone.h:105
SIG_TONE_TX_PASSTHROUGH
@ SIG_TONE_TX_PASSTHROUGH
Definition: sig_tone.h:78
SIG_TONE_1_PRESENT
@ SIG_TONE_1_PRESENT
Definition: sig_tone.h:70
sig_tone_descriptor_t::notch
const sig_tone_notch_coeffs_t * notch[2]
The coefficients for the cascaded bi-quads notch filter.
Definition: private/sig_tone.h:110
sig_tone_flat_coeffs_t
The coefficient set for a bi-quad that makes a signalling flat filter. Some signalling tone schemes r...
Definition: private/sig_tone.h:53
sig_tone_tx_release
int sig_tone_tx_release(sig_tone_tx_state_t *s)
Release a signalling tone transmitter context.
Definition: sig_tone.c:352
power_meter_level_dbm0
int32_t power_meter_level_dbm0(float level)
Get the current power meter reading, in dBm0.
Definition: power_meter.c:91
sig_tone_rx_state_s::last_sample_tone_present
int last_sample_tone_present
The tone pattern on the last audio sample.
Definition: private/sig_tone.h:204
sig_tone_rx_init
sig_tone_rx_state_t * sig_tone_rx_init(sig_tone_rx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data)
Initialise a signalling tone context.
Definition: sig_tone.c:632
SIG_TONE_RX_PASSTHROUGH
@ SIG_TONE_RX_PASSTHROUGH
Definition: sig_tone.h:80
sig_tone_rx_state_s::signalling_state_duration
int signalling_state_duration
???
Definition: private/sig_tone.h:225
SIG_TONE_1_CHANGE
@ SIG_TONE_1_CHANGE
Definition: sig_tone.h:72
sig_tone_rx_state_s::flat_mode_timeout
int flat_mode_timeout
???
Definition: private/sig_tone.h:218
sig_tone_tx_state_s::phase_rate
int32_t phase_rate[2]
Definition: private/sig_tone.h:136
sig_tone_rx_state_s::notch_z2
float notch_z2[2]
The z's for the notch filter.
Definition: private/sig_tone.h:184
power_meter_init
power_meter_t * power_meter_init(power_meter_t *s, int shift)
Initialise a power meter context.
Definition: power_meter.c:50
sig_tone_descriptor_t::sharp_flat_timeout
int sharp_flat_timeout
Some signalling tone detectors use a sharp initial filter, changing to a broader, flatter,...
Definition: private/sig_tone.h:92
sig_tone_tx_state_s
Definition: private/sig_tone.h:126
sig_tone_rx_free
int sig_tone_rx_free(sig_tone_rx_state_t *s)
Free a signalling tone receiver context.
Definition: sig_tone.c:686
sig_tone_descriptor_t
Definition: private/sig_tone.h:75
sig_tone_rx_state_s::notch_enabled
int notch_enabled
TRUE if the notch filter is enabled in the media path.
Definition: private/sig_tone.h:216
sig_tone_rx_state_s::flat_mode
int flat_mode
TRUE if in flat mode. FALSE if in sharp mode.
Definition: private/sig_tone.h:214
sig_tone_descriptor_t::tone_freq
int tone_freq[2]
The tones used.
Definition: private/sig_tone.h:77
sig_tone_rx_state_s::notch_z1
float notch_z1[2]
The z's for the notch filter.
Definition: private/sig_tone.h:182
sig_tone_descriptor_t::tone_on_check_time
int tone_on_check_time
The tone on persistence check, in audio samples.
Definition: private/sig_tone.h:103
dds.h