tone_generate.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * tone_generate.h - General telephony tone generation, and specific
00005  *                   generation of DTMF, and network supervisory tones.
00006  *
00007  * Written by Steve Underwood <steveu@coppice.org>
00008  *
00009  * Copyright (C) 2001 Steve Underwood
00010  *
00011  * All rights reserved.
00012  *
00013  * This program is free software; you can redistribute it and/or modify
00014  * it under the terms of the GNU General Public License as published by
00015  * the Free Software Foundation; either version 2 of the License, or
00016  * (at your option) any later version.
00017  *
00018  * This program is distributed in the hope that it will be useful,
00019  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00020  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00021  * GNU General Public License for more details.
00022  *
00023  * You should have received a copy of the GNU General Public License
00024  * along with this program; if not, write to the Free Software
00025  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00026  *
00027  * $Id: tone_generate.h,v 1.15 2006/01/31 05:34:27 steveu Exp $
00028  */
00029 
00030 /*! \file */
00031 
00032 #if !defined(_TONE_GENERATE_H_)
00033 #define _TONE_GENERATE_H_
00034 
00035 /*! \page tone_generation_page Tone generation
00036 \section tone_generation_page_sec_1 What does it do?
00037 The tone generation module provides for the generation of cadenced tones,
00038 suitable for a wide range of telephony applications. 
00039 
00040 \section tone_generation_page_sec_2 How does it work?
00041 Oscillators are a problem. They oscillate due to instability, and yet we need
00042 them to behave in a stable manner. A look around the web will reveal many papers
00043 on this subject. Many describe rather complex solutions to the problem. However,
00044 we are only concerned with telephony applications. It is possible to generate
00045 the tones we need with a very simple efficient scheme. It is also practical to
00046 use an exhaustive test to prove the oscillator is stable under all the
00047 conditions in which we will use it. 
00048 */
00049 
00050 /*! \page dtmf_tx_page DTMF tone generation
00051 \section dtmf_tx_page_sec_1 What does it do?
00052 
00053 The DTMF tone generation module provides for the generation of the
00054 repertoire of 16 DTMF dual tones. 
00055 
00056 \section dtmf_tx_page_sec_2 How does it work?
00057 */
00058 
00059 /*! \page mfc_r2_tone_generation_page MFC/R2 tone generation
00060 \section mfc_r2_tone_generation_page_sec_1 What does it do?
00061 The MFC/R2 tone generation module provides for the generation of the
00062 repertoire of 15 dual tones needs for the digital MFC/R2 signalling protocol. 
00063 
00064 \section mfc_r2_tone_generation_page_sec_2 How does it work?
00065 */
00066 
00067 /*! \page bell_mf_tone_generation_page Bell MF tone generation
00068 \section bell_mf_tone_generation_page_sec_1 What does it do?
00069 The Bell MF tone generation module provides for the generation of the
00070 repertoire of 15 dual tones needs for various Bell MF signalling protocols. 
00071 
00072 \section bell_mf_tone_generation_page_sec_2 How does it work?
00073 Basic Bell MF tone generation specs:
00074     - Tone on time = KP: 100+-7ms. All other signals: 68+-7ms
00075     - Tone off time (between digits) = 68+-7ms
00076     - Frequency tolerance +- 1.5%
00077     - Signal level -7+-1dBm per frequency
00078 */
00079 
00080 #if !defined(MAX_DTMF_DIGITS)
00081 #define MAX_DTMF_DIGITS 128
00082 #endif
00083 
00084 /*!
00085     Cadenced dual tone generator descriptor.
00086 */
00087 typedef struct
00088 {
00089     int32_t phase_rate[2];
00090     int gain[2];
00091     
00092     int duration[4];
00093 
00094     int repeat;
00095 } tone_gen_descriptor_t;
00096 
00097 /*!
00098     Cadenced dual tone generator state descriptor. This defines the state of
00099     a single working instance of a generator.
00100 */
00101 typedef struct
00102 {
00103     int32_t phase_rate[2];
00104     int gain[2];
00105 
00106     uint32_t phase[2];
00107 
00108     int duration[4];
00109     
00110     int repeat;
00111 
00112     int current_section;
00113     int current_position;
00114 } tone_gen_state_t;
00115 
00116 typedef enum
00117 {
00118     BELL_MF_TONES,
00119     R2_MF_TONES,
00120     SOCOTEL_TONES
00121 } mf_tone_types_e;
00122 
00123 /*!
00124     DTMF generator state descriptor. This defines the state of a single
00125     working instance of a DTMF generator.
00126 */
00127 typedef struct
00128 {
00129     const char *tone_codes;
00130     tone_gen_descriptor_t *tone_descriptors;
00131     tone_gen_state_t tones;
00132     char digits[MAX_DTMF_DIGITS + 1];
00133     int current_sample;
00134     int current_digits;
00135 } dtmf_tx_state_t;
00136 
00137 typedef struct
00138 {
00139     int         f1;         /* First freq */
00140     int         f2;         /* Second freq */
00141     int8_t      level1;     /* Level of the first freq (dB) */
00142     int8_t      level2;     /* Level of the second freq (dB) */
00143     uint16_t    on_time1;   /* Tone on time (ms) */
00144     uint16_t    off_time1;  /* Minimum post tone silence (ms) */
00145     uint16_t    on_time2;   /* Tone on time (ms) */
00146     uint16_t    off_time2;  /* Minimum post tone silence (ms) */
00147     int8_t      repeat;     /* True if cyclic tone, false for one shot. */
00148 } cadenced_tone_t;
00149 
00150 #ifdef __cplusplus
00151 extern "C" {
00152 #endif
00153 
00154 void make_tone_descriptor(tone_gen_descriptor_t *desc, cadenced_tone_t *tone);
00155 void make_tone_gen_descriptor(tone_gen_descriptor_t *s,
00156                               int f1,
00157                               int l1,
00158                               int f2,
00159                               int l2,
00160                               int d1,
00161                               int d2,
00162                               int d3,
00163                               int d4,
00164                               int repeat);
00165 
00166 void tone_gen_init(tone_gen_state_t *s, tone_gen_descriptor_t *t);
00167 int tone_gen(tone_gen_state_t *s, int16_t amp[], int max_samples);
00168 
00169 /*! \brief Initialise DTMF tone generation. This should be called before
00170            any other use of the DTMF tone features. */
00171 void dtmf_gen_init(void);
00172 
00173 /*! \brief Initialise a DTMF tone generator context.
00174     \param s The DTMF generator context.
00175     \return A pointer to the DTMF generator context. */
00176 dtmf_tx_state_t *dtmf_tx_init(dtmf_tx_state_t *s);
00177 
00178 /*! \brief Generate a buffer of DTMF tones.
00179     \param s The DTMF generator context.
00180     \param amp The buffer for the generated signal.
00181     \param max_samples The required number of generated samples.
00182     \return The number of samples actually generated. This may be less than 
00183             samples if the input buffer empties. */
00184 int dtmf_tx(dtmf_tx_state_t *s, int16_t amp[], int max_samples);
00185 
00186 /*! \brief Put a string of digits in a DTMF generator's input buffer.
00187     \param s The DTMF generator context.
00188     \param digits The string of digits to be added.
00189     \return The number of digits actually added. This may be less than the
00190             length of the digit string, if the buffer fills up. */
00191 int dtmf_put(dtmf_tx_state_t *s, const char *digits);
00192 
00193 /*! \brief Initialise Bell MF tone generation. This should be called before
00194            any other use of the Bell MF tone features. */
00195 void bell_mf_gen_init(void);
00196 
00197 /*! \brief Initialise a Bell MF generator context.
00198     \param s The Bell MF generator context (same type as a DTMF context).
00199     \return A pointer to the Bell MF generator context.*/
00200 dtmf_tx_state_t *bell_mf_tx_init(dtmf_tx_state_t *s);
00201 
00202 /*! \brief Initialise MFC/R2 tone generation. This should be called before
00203            any other use of the MFC/R2 tone features. */
00204 void r2_mf_tx_init(void);
00205 
00206 /*! \brief Generate a block of R2 MF tones.
00207     \param s The R2 MF generate context.
00208     \param amp The buffer for the generated signal.
00209     \param samples The required number of generated samples.
00210     \param fwd TRUE to use the forward tone set. FALSE to use the reverse tone set.
00211     \param digit The digit to be generated. When continuing to generate the same
00212            digit as during the last call to this function, digit should be set to 0x7F.
00213     \return The number of samples actually generated. */
00214 int r2_mf_tx(tone_gen_state_t *s, int16_t amp[], int samples, int fwd, char digit);
00215 
00216 #ifdef __cplusplus
00217 }
00218 #endif
00219 
00220 #endif
00221 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1