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

Generated on Thu Mar 20 17:19:59 2008 for libspandsp by  doxygen 1.5.5