Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/bell_r2_mf.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.6pre17
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 15:50:58 +0200
parents
children
comparison
equal deleted inserted replaced
3:c6c5a16ce2f2 4:26cd8f1ef0b1
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 Lesser General Public License version 2.1,
14 * as 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 Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License 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.24 2009/02/10 13:06:47 steveu Exp $
26 */
27
28 /*! \file */
29
30 #if !defined(_SPANDSP_BELL_R2_MF_H_)
31 #define _SPANDSP_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 /*! The maximum number of Bell MF digits we can buffer. */
105 #define MAX_BELL_MF_DIGITS 128
106
107 /*!
108 Bell MF generator state descriptor. This defines the state of a single
109 working instance of a Bell MF generator.
110 */
111 typedef struct bell_mf_tx_state_s bell_mf_tx_state_t;
112
113 /*!
114 Bell MF digit detector descriptor.
115 */
116 typedef struct bell_mf_rx_state_s bell_mf_rx_state_t;
117
118 /*!
119 MFC/R2 tone detector descriptor.
120 */
121 typedef struct r2_mf_tx_state_s r2_mf_tx_state_t;
122
123 /*!
124 MFC/R2 tone detector descriptor.
125 */
126 typedef struct r2_mf_rx_state_s r2_mf_rx_state_t;
127
128 #if defined(__cplusplus)
129 extern "C"
130 {
131 #endif
132
133 /*! \brief Generate a buffer of Bell MF tones.
134 \param s The Bell MF generator context.
135 \param amp The buffer for the generated signal.
136 \param max_samples The required number of generated samples.
137 \return The number of samples actually generated. This may be less than
138 max_samples if the input buffer empties. */
139 SPAN_DECLARE(int) bell_mf_tx(bell_mf_tx_state_t *s, int16_t amp[], int max_samples);
140
141 /*! \brief Put a string of digits in a Bell MF generator's input buffer.
142 \param s The Bell MF generator context.
143 \param digits The string of digits to be added.
144 \param len The length of the string of digits. If negative, the string is
145 assumed to be a NULL terminated string.
146 \return The number of digits actually added. This may be less than the
147 length of the digit string, if the buffer fills up. */
148 SPAN_DECLARE(int) bell_mf_tx_put(bell_mf_tx_state_t *s, const char *digits, int len);
149
150 /*! \brief Initialise a Bell MF generator context.
151 \param s The Bell MF generator context.
152 \return A pointer to the Bell MF generator context.*/
153 SPAN_DECLARE(bell_mf_tx_state_t *) bell_mf_tx_init(bell_mf_tx_state_t *s);
154
155 /*! \brief Release a Bell MF generator context.
156 \param s The Bell MF generator context.
157 \return 0 for OK, else -1. */
158 SPAN_DECLARE(int) bell_mf_tx_release(bell_mf_tx_state_t *s);
159
160 /*! \brief Free a Bell MF generator context.
161 \param s The Bell MF generator context.
162 \return 0 for OK, else -1. */
163 SPAN_DECLARE(int) bell_mf_tx_free(bell_mf_tx_state_t *s);
164
165 /*! \brief Generate a block of R2 MF tones.
166 \param s The R2 MF generator context.
167 \param amp The buffer for the generated signal.
168 \param samples The required number of generated samples.
169 \return The number of samples actually generated. */
170 SPAN_DECLARE(int) r2_mf_tx(r2_mf_tx_state_t *s, int16_t amp[], int samples);
171
172 /*! \brief Generate a block of R2 MF tones.
173 \param s The R2 MF generator context.
174 \param digit The digit to be generated.
175 \return 0 for OK, or -1 for a bad request. */
176 SPAN_DECLARE(int) r2_mf_tx_put(r2_mf_tx_state_t *s, char digit);
177
178 /*! \brief Initialise an R2 MF tone generator context.
179 \param s The R2 MF generator context.
180 \param fwd TRUE if the context is for forward signals. FALSE if the
181 context is for backward signals.
182 \return A pointer to the MFC/R2 generator context.*/
183 SPAN_DECLARE(r2_mf_tx_state_t *) r2_mf_tx_init(r2_mf_tx_state_t *s, int fwd);
184
185 /*! \brief Release an R2 MF tone generator context.
186 \param s The R2 MF tone generator context.
187 \return 0 for OK, else -1. */
188 SPAN_DECLARE(int) r2_mf_tx_release(r2_mf_tx_state_t *s);
189
190 /*! \brief Free an R2 MF tone generator context.
191 \param s The R2 MF tone generator context.
192 \return 0 for OK, else -1. */
193 SPAN_DECLARE(int) r2_mf_tx_free(r2_mf_tx_state_t *s);
194
195 /*! Process a block of received Bell MF audio samples.
196 \brief Process a block of received Bell MF audio samples.
197 \param s The Bell MF receiver context.
198 \param amp The audio sample buffer.
199 \param samples The number of samples in the buffer.
200 \return The number of samples unprocessed. */
201 SPAN_DECLARE(int) bell_mf_rx(bell_mf_rx_state_t *s, const int16_t amp[], int samples);
202
203 /*! \brief Get a string of digits from a Bell MF receiver's output buffer.
204 \param s The Bell MF receiver context.
205 \param buf The buffer for the received digits.
206 \param max The maximum number of digits to be returned,
207 \return The number of digits actually returned. */
208 SPAN_DECLARE(size_t) bell_mf_rx_get(bell_mf_rx_state_t *s, char *buf, int max);
209
210 /*! \brief Initialise a Bell MF receiver context.
211 \param s The Bell MF receiver context.
212 \param callback An optional callback routine, used to report received digits. If
213 no callback routine is set, digits may be collected, using the bell_mf_rx_get()
214 function.
215 \param user_data An opaque pointer which is associated with the context,
216 and supplied in callbacks.
217 \return A pointer to the Bell MF receiver context.*/
218 SPAN_DECLARE(bell_mf_rx_state_t *) bell_mf_rx_init(bell_mf_rx_state_t *s,
219 digits_rx_callback_t callback,
220 void *user_data);
221
222 /*! \brief Release a Bell MF receiver context.
223 \param s The Bell MF receiver context.
224 \return 0 for OK, else -1. */
225 SPAN_DECLARE(int) bell_mf_rx_release(bell_mf_rx_state_t *s);
226
227 /*! \brief Free a Bell MF receiver context.
228 \param s The Bell MF receiver context.
229 \return 0 for OK, else -1. */
230 SPAN_DECLARE(int) bell_mf_rx_free(bell_mf_rx_state_t *s);
231
232 /*! Process a block of received R2 MF audio samples.
233 \brief Process a block of received R2 MF audio samples.
234 \param s The R2 MF receiver context.
235 \param amp The audio sample buffer.
236 \param samples The number of samples in the buffer.
237 \return The number of samples unprocessed. */
238 SPAN_DECLARE(int) r2_mf_rx(r2_mf_rx_state_t *s, const int16_t amp[], int samples);
239
240 /*! \brief Get the current digit from an R2 MF receiver.
241 \param s The R2 MF receiver context.
242 \return The number digits being received. */
243 SPAN_DECLARE(int) r2_mf_rx_get(r2_mf_rx_state_t *s);
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 \param callback An optional callback routine, used to report received digits. If
250 no callback routine is set, digits may be collected, using the r2_mf_rx_get()
251 function.
252 \param user_data An opaque pointer which is associated with the context,
253 and supplied in callbacks.
254 \return A pointer to the R2 MF receiver context. */
255 SPAN_DECLARE(r2_mf_rx_state_t *) r2_mf_rx_init(r2_mf_rx_state_t *s,
256 int fwd,
257 tone_report_func_t callback,
258 void *user_data);
259
260 /*! \brief Release an R2 MF receiver context.
261 \param s The R2 MF receiver context.
262 \return 0 for OK, else -1. */
263 SPAN_DECLARE(int) r2_mf_rx_release(r2_mf_rx_state_t *s);
264
265 /*! \brief Free an R2 MF receiver context.
266 \param s The R2 MF receiver context.
267 \return 0 for OK, else -1. */
268 SPAN_DECLARE(int) r2_mf_rx_free(r2_mf_rx_state_t *s);
269
270 #if defined(__cplusplus)
271 }
272 #endif
273
274 #endif
275 /*- End of file ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.