Mercurial > hg > audiostuff
comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/bell_r2_mf.h @ 5:f762bf195c4b
import spandsp-0.0.3
author | Peter Meerwald <pmeerw@cosy.sbg.ac.at> |
---|---|
date | Fri, 25 Jun 2010 16:00:21 +0200 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
4:26cd8f1ef0b1 | 5:f762bf195c4b |
---|---|
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 ------------------------------------------------------------*/ |