fsk.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * fsk.h - FSK modem transmit and receive parts
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 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 /*! \page fsk_page FSK modems
00029 \section fsk_page_sec_1 What does it do?
00030 Most of the oldest telephony modems use incoherent FSK modulation. This module can
00031 be used to implement both the transmit and receive sides of a number of these
00032 modems. There are integrated definitions for: 
00033 
00034  - V.21
00035  - V.23
00036  - Bell 103
00037  - Bell 202
00038  - Weitbrecht (Used for TDD - Telecoms Device for the Deaf)
00039 
00040 The audio output or input is a stream of 16 bit samples, at 8000 samples/second.
00041 The transmit and receive sides can be used independantly. 
00042 
00043 \section fsk_page_sec_2 The transmitter
00044 
00045 The FSK transmitter uses a DDS generator to synthesise the waveform. This
00046 naturally produces phase coherent transitions, as the phase update rate is
00047 switched, producing a clean spectrum. The symbols are not generally an integer
00048 number of samples long. However, the symbol time for the fastest data rate
00049 generally used (1200bps) is more than 7 samples long. The jitter resulting from
00050 switching at the nearest sample is, therefore, acceptable. No interpolation is
00051 used. 
00052 
00053 \section fsk_page_sec_3 The receiver
00054 
00055 The FSK receiver uses a quadrature correlation technique to demodulate the
00056 signal. Two DDS quadrature oscillators are used. The incoming signal is
00057 correlated with the oscillator signals over a period of one symbol. The
00058 oscillator giving the highest net correlation from its I and Q outputs is the
00059 one that matches the frequency being transmitted during the correlation
00060 interval. Because the transmission is totally asynchronous, the demodulation
00061 process must run sample by sample to find the symbol transitions. The
00062 correlation is performed on a sliding window basis, so the computational load of
00063 demodulating sample by sample is not great. 
00064 
00065 Two modes of symbol synchronisation are provided:
00066 
00067     - In synchronous mode, symbol transitions are smoothed, to track their true
00068       position in the prescence of high timing jitter. This provides the most
00069       reliable symbol recovery in poor signal to noise conditions. However, it
00070       takes a little time to settle, so it not really suitable for data streams
00071       which must start up instantaneously (e.g. the TDD systems used by hearing
00072       impaired people).
00073 
00074     - In asynchronous mode each transition is taken at face value, with no temporal
00075       smoothing. There is no settling time for this mode, but when the signal to
00076       noise ratio is very poor it does not perform as well as the synchronous mode.
00077 */
00078 
00079 #if !defined(_SPANDSP_FSK_H_)
00080 #define _SPANDSP_FSK_H_
00081 
00082 /*!
00083     FSK modem specification. This defines the frequencies, signal levels and
00084     baud rate (== bit rate for simple FSK) for a single channel of an FSK modem.
00085 */
00086 typedef struct
00087 {
00088     /*! Short text name for the modem. */
00089     const char *name;
00090     /*! The frequency of the zero bit state, in Hz */
00091     int freq_zero;
00092     /*! The frequency of the one bit state, in Hz */
00093     int freq_one;
00094     /*! The transmit power level, in dBm0 */
00095     int tx_level;
00096     /*! The minimum acceptable receive power level, in dBm0 */
00097     int min_level;
00098     /*! The bit rate of the modem, in units of 1/100th bps */
00099     int baud_rate;
00100 } fsk_spec_t;
00101 
00102 /* Predefined FSK modem channels */
00103 enum
00104 {
00105     FSK_V21CH1 = 0,
00106     FSK_V21CH2,
00107     FSK_V23CH1,
00108     FSK_V23CH2,
00109     FSK_BELL103CH1,
00110     FSK_BELL103CH2,
00111     FSK_BELL202,
00112     FSK_WEITBRECHT,     /* 45.45 baud version, used for TDD (Telecom Device for the Deaf) */
00113     FSK_WEITBRECHT50    /* 50 baud version, used for TDD (Telecom Device for the Deaf) */
00114 };
00115 
00116 enum
00117 {
00118     FSK_FRAME_MODE_ASYNC = 0,
00119     FSK_FRAME_MODE_SYNC = 1,
00120     FSK_FRAME_MODE_5N1_FRAMES = 7,      /* 5 bits of data + start bit + stop bit */
00121     FSK_FRAME_MODE_7N1_FRAMES = 9,      /* 7 bits of data + start bit + stop bit */
00122     FSK_FRAME_MODE_8N1_FRAMES = 10      /* 8 bits of data + start bit + stop bit */
00123 };
00124 
00125 SPAN_DECLARE_DATA extern const fsk_spec_t preset_fsk_specs[];
00126 
00127 /*!
00128     FSK modem transmit descriptor. This defines the state of a single working
00129     instance of an FSK modem transmitter.
00130 */
00131 typedef struct fsk_tx_state_s fsk_tx_state_t;
00132 
00133 /* The longest window will probably be 106 for 75 baud */
00134 #define FSK_MAX_WINDOW_LEN 128
00135 
00136 /*!
00137     FSK modem receive descriptor. This defines the state of a single working
00138     instance of an FSK modem receiver.
00139 */
00140 typedef struct fsk_rx_state_s fsk_rx_state_t;
00141 
00142 #if defined(__cplusplus)
00143 extern "C"
00144 {
00145 #endif
00146 
00147 /*! Initialise an FSK modem transmit context.
00148     \brief Initialise an FSK modem transmit context.
00149     \param s The modem context.
00150     \param spec The specification of the modem tones and rate.
00151     \param get_bit The callback routine used to get the data to be transmitted.
00152     \param user_data An opaque pointer.
00153     \return A pointer to the modem context, or NULL if there was a problem. */
00154 SPAN_DECLARE(fsk_tx_state_t *) fsk_tx_init(fsk_tx_state_t *s,
00155                                            const fsk_spec_t *spec,
00156                                            get_bit_func_t get_bit,
00157                                            void *user_data);
00158 
00159 SPAN_DECLARE(int) fsk_tx_restart(fsk_tx_state_t *s, const fsk_spec_t *spec);
00160     
00161 SPAN_DECLARE(int) fsk_tx_release(fsk_tx_state_t *s);
00162 
00163 SPAN_DECLARE(int) fsk_tx_free(fsk_tx_state_t *s);
00164 
00165 /*! Adjust an FSK modem transmit context's power output.
00166     \brief Adjust an FSK modem transmit context's power output.
00167     \param s The modem context.
00168     \param power The power level, in dBm0 */
00169 SPAN_DECLARE(void) fsk_tx_power(fsk_tx_state_t *s, float power);
00170 
00171 SPAN_DECLARE(void) fsk_tx_set_get_bit(fsk_tx_state_t *s, get_bit_func_t get_bit, void *user_data);
00172 
00173 /*! Change the modem status report function associated with an FSK modem transmit context.
00174     \brief Change the modem status report function associated with an FSK modem transmit context.
00175     \param s The modem context.
00176     \param handler The callback routine used to report modem status changes.
00177     \param user_data An opaque pointer. */
00178 SPAN_DECLARE(void) fsk_tx_set_modem_status_handler(fsk_tx_state_t *s, modem_tx_status_func_t handler, void *user_data);
00179 
00180 /*! Generate a block of FSK modem audio samples.
00181     \brief Generate a block of FSK modem audio samples.
00182     \param s The modem context.
00183     \param amp The audio sample buffer.
00184     \param len The number of samples to be generated.
00185     \return The number of samples actually generated.
00186 */
00187 SPAN_DECLARE_NONSTD(int) fsk_tx(fsk_tx_state_t *s, int16_t amp[], int len);
00188 
00189 /*! Get the current received signal power.
00190     \param s The modem context.
00191     \return The signal power, in dBm0. */
00192 SPAN_DECLARE(float) fsk_rx_signal_power(fsk_rx_state_t *s);
00193 
00194 /*! Adjust an FSK modem receive context's carrier detect power threshold.
00195     \brief Adjust an FSK modem receive context's carrier detect power threshold.
00196     \param s The modem context.
00197     \param cutoff The power level, in dBm0 */
00198 SPAN_DECLARE(void) fsk_rx_signal_cutoff(fsk_rx_state_t *s, float cutoff);
00199 
00200 /*! Initialise an FSK modem receive context.
00201     \brief Initialise an FSK modem receive context.
00202     \param s The modem context.
00203     \param spec The specification of the modem tones and rate.
00204     \param framing_mode 0 for fully asynchronous mode. 1 for synchronous mode. >1 for
00205            this many bits per asynchronous character frame.
00206     \param put_bit The callback routine used to put the received data.
00207     \param user_data An opaque pointer.
00208     \return A pointer to the modem context, or NULL if there was a problem. */
00209 SPAN_DECLARE(fsk_rx_state_t *) fsk_rx_init(fsk_rx_state_t *s,
00210                                            const fsk_spec_t *spec,
00211                                            int framing_mode,
00212                                            put_bit_func_t put_bit,
00213                                            void *user_data);
00214 
00215 SPAN_DECLARE(int) fsk_rx_restart(fsk_rx_state_t *s, const fsk_spec_t *spec, int framing_mode);
00216 
00217 SPAN_DECLARE(int) fsk_rx_release(fsk_rx_state_t *s);
00218 
00219 SPAN_DECLARE(int) fsk_rx_free(fsk_rx_state_t *s);
00220 
00221 /*! Process a block of received FSK modem audio samples.
00222     \brief Process a block of received FSK modem audio samples.
00223     \param s The modem context.
00224     \param amp The audio sample buffer.
00225     \param len The number of samples in the buffer.
00226     \return The number of samples unprocessed.
00227 */
00228 SPAN_DECLARE_NONSTD(int) fsk_rx(fsk_rx_state_t *s, const int16_t *amp, int len);
00229 
00230 /*! Fake processing of a missing block of received FSK modem audio samples
00231     (e.g due to packet loss).
00232     \brief Fake processing of a missing block of received FSK modem audio samples.
00233     \param s The modem context.
00234     \param len The number of samples to fake.
00235     \return The number of samples unprocessed.
00236 */
00237 SPAN_DECLARE_NONSTD(int) fsk_rx_fillin(fsk_rx_state_t *s, int len);
00238 
00239 SPAN_DECLARE(void) fsk_rx_set_put_bit(fsk_rx_state_t *s, put_bit_func_t put_bit, void *user_data);
00240 
00241 /*! Change the modem status report function associated with an FSK modem receive context.
00242     \brief Change the modem status report function associated with an FSK modem receive context.
00243     \param s The modem context.
00244     \param handler The callback routine used to report modem status changes.
00245     \param user_data An opaque pointer. */
00246 SPAN_DECLARE(void) fsk_rx_set_modem_status_handler(fsk_rx_state_t *s, modem_rx_status_func_t handler, void *user_data);
00247 
00248 #if defined(__cplusplus)
00249 }
00250 #endif
00251 
00252 #endif
00253 /*- End of file ------------------------------------------------------------*/

Generated on 9 Jul 2012 for spandsp by  doxygen 1.6.1