|
5
|
1 /*
|
|
|
2 * SpanDSP - a series of DSP components for telephony
|
|
|
3 *
|
|
|
4 * bell_r2_mf.h - Bell MF and MFC/R2 tone generation and detection.
|
|
|
5 *
|
|
|
6 * Written by Steve Underwood <steveu@coppice.org>
|
|
|
7 *
|
|
|
8 * Copyright (C) 2001 Steve Underwood
|
|
|
9 *
|
|
|
10 * All rights reserved.
|
|
|
11 *
|
|
|
12 * This program is free software; you can redistribute it and/or modify
|
|
|
13 * it under the terms of the GNU General Public License version 2, as
|
|
|
14 * published by the Free Software Foundation.
|
|
|
15 *
|
|
|
16 * This program is distributed in the hope that it will be useful,
|
|
|
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
19 * GNU General Public License for more details.
|
|
|
20 *
|
|
|
21 * You should have received a copy of the GNU General Public License
|
|
|
22 * along with this program; if not, write to the Free Software
|
|
|
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
24 *
|
|
|
25 * $Id: bell_r2_mf.h,v 1.5 2006/10/24 13:22:01 steveu Exp $
|
|
|
26 */
|
|
|
27
|
|
|
28 /*! \file */
|
|
|
29
|
|
|
30 #if !defined(_BELL_R2_MF_H_)
|
|
|
31 #define _BELL_R2_MF_H_
|
|
|
32
|
|
|
33 /*! \page mfc_r2_tone_generation_page MFC/R2 tone generation
|
|
|
34 \section mfc_r2_tone_generation_page_sec_1 What does it do?
|
|
|
35 The MFC/R2 tone generation module provides for the generation of the
|
|
|
36 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol.
|
|
|
37
|
|
|
38 \section mfc_r2_tone_generation_page_sec_2 How does it work?
|
|
|
39 */
|
|
|
40
|
|
|
41 /*! \page bell_mf_tone_generation_page Bell MF tone generation
|
|
|
42 \section bell_mf_tone_generation_page_sec_1 What does it do?
|
|
|
43 The Bell MF tone generation module provides for the generation of the
|
|
|
44 repertoire of 15 dual tones needs for various Bell MF signalling protocols.
|
|
|
45
|
|
|
46 \section bell_mf_tone_generation_page_sec_2 How does it work?
|
|
|
47 Basic Bell MF tone generation specs:
|
|
|
48 - Tone on time = KP: 100+-7ms. All other signals: 68+-7ms
|
|
|
49 - Tone off time (between digits) = 68+-7ms
|
|
|
50 - Frequency tolerance +- 1.5%
|
|
|
51 - Signal level -7+-1dBm per frequency
|
|
|
52 */
|
|
|
53
|
|
|
54 /*! \page mfc_r2_tone_rx_page MFC/R2 tone receiver
|
|
|
55
|
|
|
56 \section mfc_r2_tone_rx_page_sec_1 What does it do?
|
|
|
57 The MFC/R2 tone receiver module provides for the detection of the
|
|
|
58 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol.
|
|
|
59 It is compliant with ITU-T Q.441D.
|
|
|
60
|
|
|
61 \section mfc_r2_tone_rx_page_sec_2 How does it work?
|
|
|
62 Basic MFC/R2 tone detection specs:
|
|
|
63 - Receiver response range: -5dBm to -35dBm
|
|
|
64 - Difference in level for a pair of frequencies
|
|
|
65 - Adjacent tones: <5dB
|
|
|
66 - Non-adjacent tones: <7dB
|
|
|
67 - Receiver not to detect a signal of 2 frequencies of level -5dB and
|
|
|
68 duration <7ms.
|
|
|
69 - Receiver not to recognise a signal of 2 frequencies having a difference
|
|
|
70 in level >=20dB.
|
|
|
71 - Max received signal frequency error: +-10Hz
|
|
|
72 - The sum of the operate and release times of a 2 frequency signal not to
|
|
|
73 exceed 80ms (there are no individual specs for the operate and release
|
|
|
74 times).
|
|
|
75 - Receiver not to release for signal interruptions <=7ms.
|
|
|
76 - System malfunction due to signal interruptions >7ms (typically 20ms) is
|
|
|
77 prevented by further logic elements.
|
|
|
78 */
|
|
|
79
|
|
|
80 /*! \page bell_mf_tone_rx_page Bell MF tone receiver
|
|
|
81
|
|
|
82 \section bell_mf_tone_rx_page_sec_1 What does it do?
|
|
|
83 The Bell MF tone receiver module provides for the detection of the
|
|
|
84 repertoire of 15 dual tones needs for various Bell MF signalling protocols.
|
|
|
85 It is compliant with ITU-T Q.320, ITU-T Q.322, ITU-T Q.323B.
|
|
|
86
|
|
|
87 \section bell_mf_tone_rx_page_sec_2 How does it work?
|
|
|
88 Basic Bell MF tone detection specs:
|
|
|
89 - Frequency tolerance +- 1.5% +-10Hz
|
|
|
90 - Signal level -14dBm to 0dBm
|
|
|
91 - Perform a "two and only two tones present" test.
|
|
|
92 - Twist <= 6dB accepted
|
|
|
93 - Receiver sensitive to signals above -22dBm per frequency
|
|
|
94 - Test for a minimum of 55ms if KP, or 30ms of other signals.
|
|
|
95 - Signals to be recognised if the two tones arrive within 8ms of each other.
|
|
|
96 - Invalid signals result in the return of the re-order tone.
|
|
|
97
|
|
|
98 Note: Above -3dBm the signal starts to clip. We can detect with a little clipping,
|
|
|
99 but not up to 0dBm, which the above spec seems to require. There isn't a lot
|
|
|
100 we can do about that. Is the spec. incorrectly worded about the dBm0 reference
|
|
|
101 point, or have I misunderstood it?
|
|
|
102 */
|
|
|
103
|
|
|
104 #define MAX_BELL_MF_DIGITS 128
|
|
|
105
|
|
|
106 typedef enum
|
|
|
107 {
|
|
|
108 BELL_MF_TONES,
|
|
|
109 R2_MF_TONES,
|
|
|
110 SOCOTEL_TONES
|
|
|
111 } mf_tone_types_e;
|
|
|
112
|
|
|
113 /*!
|
|
|
114 Bell MF generator state descriptor. This defines the state of a single
|
|
|
115 working instance of a Bell MF generator.
|
|
|
116 */
|
|
|
117 typedef struct
|
|
|
118 {
|
|
|
119 tone_gen_descriptor_t *tone_descriptors;
|
|
|
120 tone_gen_state_t tones;
|
|
|
121 char digits[MAX_BELL_MF_DIGITS + 1];
|
|
|
122 int current_sample;
|
|
|
123 size_t current_digits;
|
|
|
124 } bell_mf_tx_state_t;
|
|
|
125
|
|
|
126 /*!
|
|
|
127 Bell MF digit detector descriptor.
|
|
|
128 */
|
|
|
129 typedef struct
|
|
|
130 {
|
|
|
131 /*! Optional callback funcion to deliver received digits. */
|
|
|
132 void (*callback)(void *data, const char *digits, int len);
|
|
|
133 /*! An opaque pointer passed to the callback function. */
|
|
|
134 void *callback_data;
|
|
|
135 /*! Tone detector working states */
|
|
|
136 goertzel_state_t out[6];
|
|
|
137 /*! Short term history of results from the tone detection, using in persistence checking */
|
|
|
138 uint8_t hits[5];
|
|
|
139 /*! The current sample number within a processing block. */
|
|
|
140 int current_sample;
|
|
|
141
|
|
|
142 /*! The received digits buffer. This is a NULL terminated string. */
|
|
|
143 char digits[MAX_BELL_MF_DIGITS + 1];
|
|
|
144 /*! The number of digits currently in the digit buffer. */
|
|
|
145 int current_digits;
|
|
|
146 /*! The number of digits which have been lost due to buffer overflows. */
|
|
|
147 int lost_digits;
|
|
|
148 } bell_mf_rx_state_t;
|
|
|
149
|
|
|
150 /*!
|
|
|
151 MFC/R2 tone detector descriptor.
|
|
|
152 */
|
|
|
153 typedef struct
|
|
|
154 {
|
|
|
155 tone_gen_state_t tone;
|
|
|
156 } r2_mf_tx_state_t;
|
|
|
157
|
|
|
158 /*!
|
|
|
159 MFC/R2 tone detector descriptor.
|
|
|
160 */
|
|
|
161 typedef struct
|
|
|
162 {
|
|
|
163 /*! TRUE is we are detecting forward tones. FALSE if we are detecting backward tones */
|
|
|
164 int fwd;
|
|
|
165 /*! Tone detector working states */
|
|
|
166 goertzel_state_t out[6];
|
|
|
167 int samples;
|
|
|
168 int current_sample;
|
|
|
169 } r2_mf_rx_state_t;
|
|
|
170
|
|
|
171 #ifdef __cplusplus
|
|
|
172 extern "C" {
|
|
|
173 #endif
|
|
|
174
|
|
|
175 /*! \brief Generate a buffer of Bell MF tones.
|
|
|
176 \param s The Bell MF generator context.
|
|
|
177 \param amp The buffer for the generated signal.
|
|
|
178 \param max_samples The required number of generated samples.
|
|
|
179 \return The number of samples actually generated. This may be less than
|
|
|
180 samples if the input buffer empties. */
|
|
|
181 int bell_mf_tx(bell_mf_tx_state_t *s, int16_t amp[], int max_samples);
|
|
|
182
|
|
|
183 /*! \brief Put a string of digits in a Bell MF generator's input buffer.
|
|
|
184 \param s The Bell MF generator context.
|
|
|
185 \param digits The string of digits to be added.
|
|
|
186 \return The number of digits actually added. This may be less than the
|
|
|
187 length of the digit string, if the buffer fills up. */
|
|
|
188 size_t bell_mf_tx_put(bell_mf_tx_state_t *s, const char *digits);
|
|
|
189
|
|
|
190 /*! \brief Initialise a Bell MF generator context.
|
|
|
191 \param s The Bell MF generator context.
|
|
|
192 \return A pointer to the Bell MF generator context.*/
|
|
|
193 bell_mf_tx_state_t *bell_mf_tx_init(bell_mf_tx_state_t *s);
|
|
|
194
|
|
|
195 /*! \brief Generate a block of R2 MF tones.
|
|
|
196 \param s The R2 MF generator context.
|
|
|
197 \param amp The buffer for the generated signal.
|
|
|
198 \param samples The required number of generated samples.
|
|
|
199 \param fwd TRUE to use the forward tone set. FALSE to use the reverse tone set.
|
|
|
200 \param digit The digit to be generated. When continuing to generate the same
|
|
|
201 digit as during the last call to this function, digit should be set to 0x7F.
|
|
|
202 \return The number of samples actually generated. */
|
|
|
203 int r2_mf_tx(r2_mf_tx_state_t *s, int16_t amp[], int samples, int fwd, char digit);
|
|
|
204
|
|
|
205 /*! \brief Initialise an MFC/R2 tone generator context.
|
|
|
206 \param s The R2 MF generator context.
|
|
|
207 \return A pointer to the MFC/R2 generator context.*/
|
|
|
208 r2_mf_tx_state_t *r2_mf_tx_init(r2_mf_tx_state_t *s);
|
|
|
209
|
|
|
210 /*! Process a block of received Bell MF audio samples.
|
|
|
211 \brief Process a block of received Bell MF audio samples.
|
|
|
212 \param s The Bell MF receiver context.
|
|
|
213 \param amp The audio sample buffer.
|
|
|
214 \param samples The number of samples in the buffer.
|
|
|
215 \return The number of samples unprocessed. */
|
|
|
216 int bell_mf_rx(bell_mf_rx_state_t *s, const int16_t amp[], int samples);
|
|
|
217
|
|
|
218 /*! \brief Get a string of digits from a Bell MF receiver's output buffer.
|
|
|
219 \param s The Bell MF receiver context.
|
|
|
220 \param digits The buffer for the received digits.
|
|
|
221 \param max The maximum number of digits to be returned,
|
|
|
222 \return The number of digits actually returned. */
|
|
|
223 size_t bell_mf_rx_get(bell_mf_rx_state_t *s, char *buf, int max);
|
|
|
224
|
|
|
225 /*! \brief Initialise a Bell MF receiver context.
|
|
|
226 \param s The Bell MF receiver context.
|
|
|
227 \param callback An optional callback routine, used to report received digits. If
|
|
|
228 no callback routine is set, digits may be collected, using the bell_mf_rx_get()
|
|
|
229 function.
|
|
|
230 \param user_data An opaque pointer which is associated with the context,
|
|
|
231 and supplied in callbacks.
|
|
|
232 \return A pointer to the Bell MF receiver context.*/
|
|
|
233 bell_mf_rx_state_t *bell_mf_rx_init(bell_mf_rx_state_t *s,
|
|
|
234 void (*callback)(void *user_data, const char *digits, int len),
|
|
|
235 void *user_data);
|
|
|
236
|
|
|
237 /*! Process a block of received R2 MF audio samples.
|
|
|
238 \brief Process a block of received R2 MF audio samples.
|
|
|
239 \param s The R2 MF receiver context.
|
|
|
240 \param amp The audio sample buffer.
|
|
|
241 \param samples The number of samples in the buffer.
|
|
|
242 \return The number of samples unprocessed. */
|
|
|
243 int r2_mf_rx(r2_mf_rx_state_t *s, const int16_t amp[], int samples);
|
|
|
244
|
|
|
245 /*! \brief Initialise an R2 MF receiver context.
|
|
|
246 \param s The R2 MF receiver context.
|
|
|
247 \param fwd TRUE if the context is for forward signals. FALSE if the
|
|
|
248 context is for backward signals.
|
|
|
249 \return A pointer to the R2 MF receiver context. */
|
|
|
250 r2_mf_rx_state_t *r2_mf_rx_init(r2_mf_rx_state_t *s, int fwd);
|
|
|
251
|
|
|
252 #ifdef __cplusplus
|
|
|
253 }
|
|
|
254 #endif
|
|
|
255
|
|
|
256 #endif
|
|
|
257 /*- End of file ------------------------------------------------------------*/
|
