bell_r2_mf.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * bell_r2_mf.h - Bell MF and MFC/R2 tone generation and detection.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2001 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 /*! \file */
00027 
00028 #if !defined(_SPANDSP_BELL_R2_MF_H_)
00029 #define _SPANDSP_BELL_R2_MF_H_
00030 
00031 /*! \page mfc_r2_tone_generation_page MFC/R2 tone generation
00032 \section mfc_r2_tone_generation_page_sec_1 What does it do?
00033 The MFC/R2 tone generation module provides for the generation of the
00034 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol. 
00035 
00036 \section mfc_r2_tone_generation_page_sec_2 How does it work?
00037 */
00038 
00039 /*! \page bell_mf_tone_generation_page Bell MF tone generation
00040 \section bell_mf_tone_generation_page_sec_1 What does it do?
00041 The Bell MF tone generation module provides for the generation of the
00042 repertoire of 15 dual tones needs for various Bell MF signalling protocols. 
00043 
00044 \section bell_mf_tone_generation_page_sec_2 How does it work?
00045 Basic Bell MF tone generation specs:
00046     - Tone on time = KP: 100+-7ms. All other signals: 68+-7ms
00047     - Tone off time (between digits) = 68+-7ms
00048     - Frequency tolerance +- 1.5%
00049     - Signal level -7+-1dBm per frequency
00050 */
00051 
00052 /*! \page mfc_r2_tone_rx_page MFC/R2 tone receiver
00053 
00054 \section mfc_r2_tone_rx_page_sec_1 What does it do?
00055 The MFC/R2 tone receiver module provides for the detection of the
00056 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol. 
00057 It is compliant with ITU-T Q.441D.
00058 
00059 \section mfc_r2_tone_rx_page_sec_2 How does it work?
00060 Basic MFC/R2 tone detection specs:
00061     - Receiver response range: -5dBm to -35dBm
00062     - Difference in level for a pair of frequencies
00063         - Adjacent tones: <5dB
00064         - Non-adjacent tones: <7dB
00065     - Receiver not to detect a signal of 2 frequencies of level -5dB and
00066       duration <7ms.
00067     - Receiver not to recognise a signal of 2 frequencies having a difference
00068       in level >=20dB.
00069     - Max received signal frequency error: +-10Hz
00070     - The sum of the operate and release times of a 2 frequency signal not to
00071       exceed 80ms (there are no individual specs for the operate and release
00072       times).
00073     - Receiver not to release for signal interruptions <=7ms.
00074     - System malfunction due to signal interruptions >7ms (typically 20ms) is
00075       prevented by further logic elements.
00076 */
00077 
00078 /*! \page bell_mf_tone_rx_page Bell MF tone receiver
00079 
00080 \section bell_mf_tone_rx_page_sec_1 What does it do?
00081 The Bell MF tone receiver module provides for the detection of the
00082 repertoire of 15 dual tones needs for various Bell MF signalling protocols. 
00083 It is compliant with ITU-T Q.320, ITU-T Q.322, ITU-T Q.323B.
00084 
00085 \section bell_mf_tone_rx_page_sec_2 How does it work?
00086 Basic Bell MF tone detection specs:
00087     - Frequency tolerance +- 1.5% +-10Hz
00088     - Signal level -14dBm to 0dBm
00089     - Perform a "two and only two tones present" test.
00090     - Twist <= 6dB accepted
00091     - Receiver sensitive to signals above -22dBm per frequency
00092     - Test for a minimum of 55ms if KP, or 30ms of other signals.
00093     - Signals to be recognised if the two tones arrive within 8ms of each other.
00094     - Invalid signals result in the return of the re-order tone.
00095 
00096 Note: Above -3dBm the signal starts to clip. We can detect with a little clipping,
00097       but not up to 0dBm, which the above spec seems to require. There isn't a lot
00098       we can do about that. Is the spec. incorrectly worded about the dBm0 reference
00099       point, or have I misunderstood it?
00100 */
00101 
00102 /*! The maximum number of Bell MF digits we can buffer. */
00103 #define MAX_BELL_MF_DIGITS 128
00104 
00105 /*!
00106     Bell MF generator state descriptor. This defines the state of a single
00107     working instance of a Bell MF generator.
00108 */
00109 typedef struct bell_mf_tx_state_s bell_mf_tx_state_t;
00110 
00111 /*!
00112     Bell MF digit detector descriptor.
00113 */
00114 typedef struct bell_mf_rx_state_s bell_mf_rx_state_t;
00115 
00116 /*!
00117     MFC/R2 tone detector descriptor.
00118 */
00119 typedef struct r2_mf_tx_state_s r2_mf_tx_state_t;
00120 
00121 /*!
00122     MFC/R2 tone detector descriptor.
00123 */
00124 typedef struct r2_mf_rx_state_s r2_mf_rx_state_t;
00125 
00126 #if defined(__cplusplus)
00127 extern "C"
00128 {
00129 #endif
00130 
00131 /*! \brief Generate a buffer of Bell MF tones.
00132     \param s The Bell MF generator context.
00133     \param amp The buffer for the generated signal.
00134     \param max_samples The required number of generated samples.
00135     \return The number of samples actually generated. This may be less than 
00136             max_samples if the input buffer empties. */
00137 SPAN_DECLARE(int) bell_mf_tx(bell_mf_tx_state_t *s, int16_t amp[], int max_samples);
00138 
00139 /*! \brief Put a string of digits in a Bell MF generator's input buffer.
00140     \param s The Bell MF generator context.
00141     \param digits The string of digits to be added.
00142     \param len The length of the string of digits. If negative, the string is
00143            assumed to be a NULL terminated string.
00144     \return The number of digits actually added. This may be less than the
00145             length of the digit string, if the buffer fills up. */
00146 SPAN_DECLARE(int) bell_mf_tx_put(bell_mf_tx_state_t *s, const char *digits, int len);
00147 
00148 /*! \brief Initialise a Bell MF generator context.
00149     \param s The Bell MF generator context.
00150     \return A pointer to the Bell MF generator context.*/
00151 SPAN_DECLARE(bell_mf_tx_state_t *) bell_mf_tx_init(bell_mf_tx_state_t *s);
00152 
00153 /*! \brief Release a Bell MF generator context.
00154     \param s The Bell MF generator context.
00155     \return 0 for OK, else -1. */
00156 SPAN_DECLARE(int) bell_mf_tx_release(bell_mf_tx_state_t *s);
00157 
00158 /*! \brief Free a Bell MF generator context.
00159     \param s The Bell MF generator context.
00160     \return 0 for OK, else -1. */
00161 SPAN_DECLARE(int) bell_mf_tx_free(bell_mf_tx_state_t *s);
00162 
00163 /*! \brief Generate a block of R2 MF tones.
00164     \param s The R2 MF generator context.
00165     \param amp The buffer for the generated signal.
00166     \param samples The required number of generated samples.
00167     \return The number of samples actually generated. */
00168 SPAN_DECLARE(int) r2_mf_tx(r2_mf_tx_state_t *s, int16_t amp[], int samples);
00169 
00170 /*! \brief Generate a block of R2 MF tones.
00171     \param s The R2 MF generator context.
00172     \param digit The digit to be generated.
00173     \return 0 for OK, or -1 for a bad request. */
00174 SPAN_DECLARE(int) r2_mf_tx_put(r2_mf_tx_state_t *s, char digit);
00175 
00176 /*! \brief Initialise an R2 MF tone generator context.
00177     \param s The R2 MF generator context.
00178     \param fwd TRUE if the context is for forward signals. FALSE if the
00179            context is for backward signals.
00180     \return A pointer to the MFC/R2 generator context.*/
00181 SPAN_DECLARE(r2_mf_tx_state_t *) r2_mf_tx_init(r2_mf_tx_state_t *s, int fwd);
00182 
00183 /*! \brief Release an R2 MF tone generator context.
00184     \param s The R2 MF tone generator context.
00185     \return 0 for OK, else -1. */
00186 SPAN_DECLARE(int) r2_mf_tx_release(r2_mf_tx_state_t *s);
00187 
00188 /*! \brief Free an R2 MF tone generator context.
00189     \param s The R2 MF tone generator context.
00190     \return 0 for OK, else -1. */
00191 SPAN_DECLARE(int) r2_mf_tx_free(r2_mf_tx_state_t *s);
00192 
00193 /*! Process a block of received Bell MF audio samples.
00194     \brief Process a block of received Bell MF audio samples.
00195     \param s The Bell MF receiver context.
00196     \param amp The audio sample buffer.
00197     \param samples The number of samples in the buffer.
00198     \return The number of samples unprocessed. */
00199 SPAN_DECLARE(int) bell_mf_rx(bell_mf_rx_state_t *s, const int16_t amp[], int samples);
00200 
00201 /*! \brief Get a string of digits from a Bell MF receiver's output buffer.
00202     \param s The Bell MF receiver context.
00203     \param buf The buffer for the received digits.
00204     \param max The maximum  number of digits to be returned,
00205     \return The number of digits actually returned. */
00206 SPAN_DECLARE(size_t) bell_mf_rx_get(bell_mf_rx_state_t *s, char *buf, int max);
00207 
00208 /*! \brief Initialise a Bell MF receiver context.
00209     \param s The Bell MF receiver context.
00210     \param callback An optional callback routine, used to report received digits. If
00211            no callback routine is set, digits may be collected, using the bell_mf_rx_get()
00212            function.
00213     \param user_data An opaque pointer which is associated with the context,
00214            and supplied in callbacks.
00215     \return A pointer to the Bell MF receiver context.*/
00216 SPAN_DECLARE(bell_mf_rx_state_t *) bell_mf_rx_init(bell_mf_rx_state_t *s,
00217                                                    digits_rx_callback_t callback,
00218                                                    void *user_data);
00219 
00220 /*! \brief Release a Bell MF receiver context.
00221     \param s The Bell MF receiver context.
00222     \return 0 for OK, else -1. */
00223 SPAN_DECLARE(int) bell_mf_rx_release(bell_mf_rx_state_t *s);
00224 
00225 /*! \brief Free a Bell MF receiver context.
00226     \param s The Bell MF receiver context.
00227     \return 0 for OK, else -1. */
00228 SPAN_DECLARE(int) bell_mf_rx_free(bell_mf_rx_state_t *s);
00229 
00230 /*! Process a block of received R2 MF audio samples.
00231     \brief Process a block of received R2 MF audio samples.
00232     \param s The R2 MF receiver context.
00233     \param amp The audio sample buffer.
00234     \param samples The number of samples in the buffer.
00235     \return The number of samples unprocessed. */
00236 SPAN_DECLARE(int) r2_mf_rx(r2_mf_rx_state_t *s, const int16_t amp[], int samples);
00237 
00238 /*! \brief Get the current digit from an R2 MF receiver.
00239     \param s The R2 MF receiver context.
00240     \return The number digits being received. */
00241 SPAN_DECLARE(int) r2_mf_rx_get(r2_mf_rx_state_t *s);
00242 
00243 /*! \brief Initialise an R2 MF receiver context.
00244     \param s The R2 MF receiver context.
00245     \param fwd TRUE if the context is for forward signals. FALSE if the
00246            context is for backward signals.
00247     \param callback An optional callback routine, used to report received digits. If
00248            no callback routine is set, digits may be collected, using the r2_mf_rx_get()
00249            function.
00250     \param user_data An opaque pointer which is associated with the context,
00251            and supplied in callbacks.
00252     \return A pointer to the R2 MF receiver context. */
00253 SPAN_DECLARE(r2_mf_rx_state_t *) r2_mf_rx_init(r2_mf_rx_state_t *s,
00254                                                int fwd,
00255                                                tone_report_func_t callback,
00256                                                void *user_data);
00257 
00258 /*! \brief Release an R2 MF receiver context.
00259     \param s The R2 MF receiver context.
00260     \return 0 for OK, else -1. */
00261 SPAN_DECLARE(int) r2_mf_rx_release(r2_mf_rx_state_t *s);
00262 
00263 /*! \brief Free an R2 MF receiver context.
00264     \param s The R2 MF receiver context.
00265     \return 0 for OK, else -1. */
00266 SPAN_DECLARE(int) r2_mf_rx_free(r2_mf_rx_state_t *s);
00267 
00268 #if defined(__cplusplus)
00269 }
00270 #endif
00271 
00272 #endif
00273 /*- End of file ------------------------------------------------------------*/

Generated on Thu Oct 18 15:26:52 2012 for spandsp by  doxygen 1.4.7