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 ------------------------------------------------------------*/