spandsp 0.0.6

bell_r2_mf.h
Go to the documentation of this file.
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
26/*! \file */
27
28#if !defined(_SPANDSP_BELL_R2_MF_H_)
29#define _SPANDSP_BELL_R2_MF_H_
30
31/*! \page mfc_r2_tone_generation_page MFC/R2 tone generation
32\section mfc_r2_tone_generation_page_sec_1 What does it do?
33 The MFC/R2 tone generation module provides for the generation of the
34 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol.
35
36\section mfc_r2_tone_generation_page_sec_2 How does it work?
37*/
38
39/*! \page bell_mf_tone_generation_page Bell MF tone generation
40\section bell_mf_tone_generation_page_sec_1 What does it do?
41 The Bell MF tone generation module provides for the generation of the
42 repertoire of 15 dual tones needs for various Bell MF signalling protocols.
43
44\section bell_mf_tone_generation_page_sec_2 How does it work?
45 Basic Bell MF tone generation specs:
46 - Tone on time = KP: 100+-7ms. All other signals: 68+-7ms
47 - Tone off time (between digits) = 68+-7ms
48 - Frequency tolerance +- 1.5%
49 - Signal level -7+-1dBm per frequency
50*/
51
52/*! \page mfc_r2_tone_rx_page MFC/R2 tone receiver
53
54\section mfc_r2_tone_rx_page_sec_1 What does it do?
55 The MFC/R2 tone receiver module provides for the detection of the
56 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol.
57 It is compliant with ITU-T Q.441D.
58
59\section mfc_r2_tone_rx_page_sec_2 How does it work?
60 Basic MFC/R2 tone detection specs:
61 - Receiver response range: -5dBm to -35dBm
62 - Difference in level for a pair of frequencies
63 - Adjacent tones: <5dB
64 - Non-adjacent tones: <7dB
65 - Receiver not to detect a signal of 2 frequencies of level -5dB and
66 duration <7ms.
67 - Receiver not to recognise a signal of 2 frequencies having a difference
68 in level >=20dB.
69 - Max received signal frequency error: +-10Hz
70 - The sum of the operate and release times of a 2 frequency signal not to
71 exceed 80ms (there are no individual specs for the operate and release
72 times).
73 - Receiver not to release for signal interruptions <=7ms.
74 - System malfunction due to signal interruptions >7ms (typically 20ms) is
75 prevented by further logic elements.
76*/
77
78/*! \page bell_mf_tone_rx_page Bell MF tone receiver
79
80\section bell_mf_tone_rx_page_sec_1 What does it do?
81 The Bell MF tone receiver module provides for the detection of the
82 repertoire of 15 dual tones needs for various Bell MF signalling protocols.
83 It is compliant with ITU-T Q.320, ITU-T Q.322, ITU-T Q.323B.
84
85\section bell_mf_tone_rx_page_sec_2 How does it work?
86 Basic Bell MF tone detection specs:
87 - Frequency tolerance +- 1.5% +-10Hz
88 - Signal level -14dBm to 0dBm
89 - Perform a "two and only two tones present" test.
90 - Twist <= 6dB accepted
91 - Receiver sensitive to signals above -22dBm per frequency
92 - Test for a minimum of 55ms if KP, or 30ms of other signals.
93 - Signals to be recognised if the two tones arrive within 8ms of each other.
94 - Invalid signals result in the return of the re-order tone.
95
96 Note: Above -3dBm the signal starts to clip. We can detect with a little clipping,
97 but not up to 0dBm, which the above spec seems to require. There isn't a lot
98 we can do about that. Is the spec. incorrectly worded about the dBm0 reference
99 point, or have I misunderstood it?
100*/
101
102/*! The maximum number of Bell MF digits we can buffer. */
103#define MAX_BELL_MF_DIGITS 128
104
105/*!
106 Bell MF generator state descriptor. This defines the state of a single
107 working instance of a Bell MF generator.
108*/
109 typedef struct bell_mf_tx_state_s bell_mf_tx_state_t;
110
111/*!
112 Bell MF digit detector descriptor.
113*/
114 typedef struct bell_mf_rx_state_s bell_mf_rx_state_t;
115
116/*!
117 MFC/R2 tone detector descriptor.
118*/
119 typedef struct r2_mf_tx_state_s r2_mf_tx_state_t;
120
121/*!
122 MFC/R2 tone detector descriptor.
123*/
124 typedef struct r2_mf_rx_state_s r2_mf_rx_state_t;
125
126#if defined(__cplusplus)
127 extern "C"
128{
129#endif
130
131/*! \brief Generate a buffer of Bell MF tones.
132 \param s The Bell MF generator context.
133 \param amp The buffer for the generated signal.
134 \param max_samples The required number of generated samples.
135 \return The number of samples actually generated. This may be less than
136 max_samples if the input buffer empties. */
137SPAN_DECLARE(int) bell_mf_tx(bell_mf_tx_state_t *s, int16_t amp[], int max_samples);
138
139/*! \brief Put a string of digits in a Bell MF generator's input buffer.
140 \param s The Bell MF generator context.
141 \param digits The string of digits to be added.
142 \param len The length of the string of digits. If negative, the string is
143 assumed to be a NULL terminated string.
144 \return The number of digits actually added. This may be less than the
145 length of the digit string, if the buffer fills up. */
146SPAN_DECLARE(int) bell_mf_tx_put(bell_mf_tx_state_t *s, const char *digits, int len);
147
148/*! \brief Initialise a Bell MF generator context.
149 \param s The Bell MF generator context.
150 \return A pointer to the Bell MF generator context.*/
151SPAN_DECLARE(bell_mf_tx_state_t *) bell_mf_tx_init(bell_mf_tx_state_t *s);
152
153/*! \brief Release a Bell MF generator context.
154 \param s The Bell MF generator context.
155 \return 0 for OK, else -1. */
156SPAN_DECLARE(int) bell_mf_tx_release(bell_mf_tx_state_t *s);
157
158/*! \brief Free a Bell MF generator context.
159 \param s The Bell MF generator context.
160 \return 0 for OK, else -1. */
161SPAN_DECLARE(int) bell_mf_tx_free(bell_mf_tx_state_t *s);
162
163/*! \brief Generate a block of R2 MF tones.
164 \param s The R2 MF generator context.
165 \param amp The buffer for the generated signal.
166 \param samples The required number of generated samples.
167 \return The number of samples actually generated. */
168SPAN_DECLARE(int) r2_mf_tx(r2_mf_tx_state_t *s, int16_t amp[], int samples);
169
170/*! \brief Generate a block of R2 MF tones.
171 \param s The R2 MF generator context.
172 \param digit The digit to be generated.
173 \return 0 for OK, or -1 for a bad request. */
174SPAN_DECLARE(int) r2_mf_tx_put(r2_mf_tx_state_t *s, char digit);
175
176/*! \brief Initialise an R2 MF tone generator context.
177 \param s The R2 MF generator context.
178 \param fwd TRUE if the context is for forward signals. FALSE if the
179 context is for backward signals.
180 \return A pointer to the MFC/R2 generator context.*/
181SPAN_DECLARE(r2_mf_tx_state_t *) r2_mf_tx_init(r2_mf_tx_state_t *s, int fwd);
182
183/*! \brief Release an R2 MF tone generator context.
184 \param s The R2 MF tone generator context.
185 \return 0 for OK, else -1. */
186SPAN_DECLARE(int) r2_mf_tx_release(r2_mf_tx_state_t *s);
187
188/*! \brief Free an R2 MF tone generator context.
189 \param s The R2 MF tone generator context.
190 \return 0 for OK, else -1. */
191SPAN_DECLARE(int) r2_mf_tx_free(r2_mf_tx_state_t *s);
192
193/*! Process a block of received Bell MF audio samples.
194 \brief Process a block of received Bell MF audio samples.
195 \param s The Bell MF receiver context.
196 \param amp The audio sample buffer.
197 \param samples The number of samples in the buffer.
198 \return The number of samples unprocessed. */
199SPAN_DECLARE(int) bell_mf_rx(bell_mf_rx_state_t *s, const int16_t amp[], int samples);
200
201/*! \brief Get a string of digits from a Bell MF receiver's output buffer.
202 \param s The Bell MF receiver context.
203 \param buf The buffer for the received digits.
204 \param max The maximum number of digits to be returned,
205 \return The number of digits actually returned. */
206SPAN_DECLARE(size_t) bell_mf_rx_get(bell_mf_rx_state_t *s, char *buf, int max);
207
208/*! \brief Initialise a Bell MF receiver context.
209 \param s The Bell MF receiver context.
210 \param callback An optional callback routine, used to report received digits. If
211 no callback routine is set, digits may be collected, using the bell_mf_rx_get()
212 function.
213 \param user_data An opaque pointer which is associated with the context,
214 and supplied in callbacks.
215 \return A pointer to the Bell MF receiver context.*/
216SPAN_DECLARE(bell_mf_rx_state_t *) bell_mf_rx_init(bell_mf_rx_state_t *s,
217 digits_rx_callback_t callback,
218 void *user_data);
219
220/*! \brief Release a Bell MF receiver context.
221 \param s The Bell MF receiver context.
222 \return 0 for OK, else -1. */
223SPAN_DECLARE(int) bell_mf_rx_release(bell_mf_rx_state_t *s);
224
225/*! \brief Free a Bell MF receiver context.
226 \param s The Bell MF receiver context.
227 \return 0 for OK, else -1. */
228SPAN_DECLARE(int) bell_mf_rx_free(bell_mf_rx_state_t *s);
229
230/*! Process a block of received R2 MF audio samples.
231 \brief Process a block of received R2 MF audio samples.
232 \param s The R2 MF receiver context.
233 \param amp The audio sample buffer.
234 \param samples The number of samples in the buffer.
235 \return The number of samples unprocessed. */
236SPAN_DECLARE(int) r2_mf_rx(r2_mf_rx_state_t *s, const int16_t amp[], int samples);
237
238/*! \brief Get the current digit from an R2 MF receiver.
239 \param s The R2 MF receiver context.
240 \return The number digits being received. */
241SPAN_DECLARE(int) r2_mf_rx_get(r2_mf_rx_state_t *s);
242
243/*! \brief Initialise an R2 MF receiver context.
244 \param s The R2 MF receiver context.
245 \param fwd TRUE if the context is for forward signals. FALSE if the
246 context is for backward signals.
247 \param callback An optional callback routine, used to report received digits. If
248 no callback routine is set, digits may be collected, using the r2_mf_rx_get()
249 function.
250 \param user_data An opaque pointer which is associated with the context,
251 and supplied in callbacks.
252 \return A pointer to the R2 MF receiver context. */
253SPAN_DECLARE(r2_mf_rx_state_t *) r2_mf_rx_init(r2_mf_rx_state_t *s,
254 int fwd,
255 tone_report_func_t callback,
256 void *user_data);
257
258/*! \brief Release an R2 MF receiver context.
259 \param s The R2 MF receiver context.
260 \return 0 for OK, else -1. */
261SPAN_DECLARE(int) r2_mf_rx_release(r2_mf_rx_state_t *s);
262
263/*! \brief Free an R2 MF receiver context.
264 \param s The R2 MF receiver context.
265 \return 0 for OK, else -1. */
266SPAN_DECLARE(int) r2_mf_rx_free(r2_mf_rx_state_t *s);
267
268#if defined(__cplusplus)
269}
270#endif
271
272#endif
273/*- End of file ------------------------------------------------------------*/
r2_mf_rx_init
r2_mf_rx_state_t * r2_mf_rx_init(r2_mf_rx_state_t *s, int fwd, tone_report_func_t callback, void *user_data)
Initialise an R2 MF receiver context.
Definition bell_r2_mf.c:807
r2_mf_rx_release
int r2_mf_rx_release(r2_mf_rx_state_t *s)
Release an R2 MF receiver context.
Definition bell_r2_mf.c:851
bell_mf_tx_init
bell_mf_tx_state_t * bell_mf_tx_init(bell_mf_tx_state_t *s)
Initialise a Bell MF generator context.
Definition bell_r2_mf.c:325
bell_mf_rx_free
int bell_mf_rx_free(bell_mf_rx_state_t *s)
Free a Bell MF receiver context.
Definition bell_r2_mf.c:673
r2_mf_tx_free
int r2_mf_tx_free(r2_mf_tx_state_t *s)
Free an R2 MF tone generator context.
Definition bell_r2_mf.c:453
bell_mf_tx_put
int bell_mf_tx_put(bell_mf_tx_state_t *s, const char *digits, int len)
Put a string of digits in a Bell MF generator's input buffer.
Definition bell_r2_mf.c:305
bell_mf_rx_get
size_t bell_mf_rx_get(bell_mf_rx_state_t *s, char *buf, int max)
Get a string of digits from a Bell MF receiver's output buffer.
Definition bell_r2_mf.c:613
r2_mf_tx_release
int r2_mf_tx_release(r2_mf_tx_state_t *s)
Release an R2 MF tone generator context.
Definition bell_r2_mf.c:447
r2_mf_tx_state_t
struct r2_mf_tx_state_s r2_mf_tx_state_t
Definition bell_r2_mf.h:119
r2_mf_rx_state_t
struct r2_mf_rx_state_s r2_mf_rx_state_t
Definition bell_r2_mf.h:124
r2_mf_tx_put
int r2_mf_tx_put(r2_mf_tx_state_t *s, char digit)
Generate a block of R2 MF tones.
Definition bell_r2_mf.c:374
r2_mf_rx
int r2_mf_rx(r2_mf_rx_state_t *s, const int16_t amp[], int samples)
Process a block of received R2 MF audio samples.
Definition bell_r2_mf.c:680
bell_mf_rx_release
int bell_mf_rx_release(bell_mf_rx_state_t *s)
Release a Bell MF receiver context.
Definition bell_r2_mf.c:667
r2_mf_tx
int r2_mf_tx(r2_mf_tx_state_t *s, int16_t amp[], int samples)
Generate a block of R2 MF tones.
Definition bell_r2_mf.c:357
bell_mf_rx_init
bell_mf_rx_state_t * bell_mf_rx_init(bell_mf_rx_state_t *s, digits_rx_callback_t callback, void *user_data)
Initialise a Bell MF receiver context.
Definition bell_r2_mf.c:628
bell_mf_rx
int bell_mf_rx(bell_mf_rx_state_t *s, const int16_t amp[], int samples)
Process a block of received Bell MF audio samples.
Definition bell_r2_mf.c:460
bell_mf_tx
int bell_mf_tx(bell_mf_tx_state_t *s, int16_t amp[], int max_samples)
Generate a buffer of Bell MF tones.
Definition bell_r2_mf.c:281
bell_mf_tx_state_t
struct bell_mf_tx_state_s bell_mf_tx_state_t
Definition bell_r2_mf.h:109
r2_mf_tx_init
r2_mf_tx_state_t * r2_mf_tx_init(r2_mf_tx_state_t *s, int fwd)
Initialise an R2 MF tone generator context.
Definition bell_r2_mf.c:394
r2_mf_rx_get
int r2_mf_rx_get(r2_mf_rx_state_t *s)
Get the current digit from an R2 MF receiver.
Definition bell_r2_mf.c:801
r2_mf_rx_free
int r2_mf_rx_free(r2_mf_rx_state_t *s)
Free an R2 MF receiver context.
Definition bell_r2_mf.c:857
bell_mf_tx_release
int bell_mf_tx_release(bell_mf_tx_state_t *s)
Release a Bell MF generator context.
Definition bell_r2_mf.c:344
bell_mf_tx_free
int bell_mf_tx_free(bell_mf_tx_state_t *s)
Free a Bell MF generator context.
Definition bell_r2_mf.c:350
bell_mf_rx_state_t
struct bell_mf_rx_state_s bell_mf_rx_state_t
Definition bell_r2_mf.h:114
bell_mf_rx_state_s
Definition private/bell_r2_mf.h:49
bell_mf_tx_state_s
Definition private/bell_r2_mf.h:34
r2_mf_rx_state_s
Definition private/bell_r2_mf.h:86
r2_mf_rx_state_s::callback
tone_report_func_t callback
Definition private/bell_r2_mf.h:88
r2_mf_rx_state_s::fwd
int fwd
Definition private/bell_r2_mf.h:92
r2_mf_tx_state_s
Definition private/bell_r2_mf.h:73