spandsp 0.0.6

fsk.h
Go to the documentation of this file.
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * fsk.h - FSK modem transmit and receive parts
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2003 Steve Underwood
9 *
10 * All rights reserved.
11 *
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License version 2.1,
14 * as published by the Free Software Foundation.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 */
25
26/*! \file */
27
28/*! \page fsk_page FSK modems
29\section fsk_page_sec_1 What does it do?
30 Most of the oldest telephony modems use incoherent FSK modulation. This module can
31 be used to implement both the transmit and receive sides of a number of these
32 modems. There are integrated definitions for:
33
34 - V.21
35 - V.23
36 - Bell 103
37 - Bell 202
38 - Weitbrecht (Used for TDD - Telecoms Device for the Deaf)
39
40 The audio output or input is a stream of 16 bit samples, at 8000 samples/second.
41 The transmit and receive sides can be used independantly.
42
43\section fsk_page_sec_2 The transmitter
44
45 The FSK transmitter uses a DDS generator to synthesise the waveform. This
46 naturally produces phase coherent transitions, as the phase update rate is
47 switched, producing a clean spectrum. The symbols are not generally an integer
48 number of samples long. However, the symbol time for the fastest data rate
49 generally used (1200bps) is more than 7 samples long. The jitter resulting from
50 switching at the nearest sample is, therefore, acceptable. No interpolation is
51 used.
52
53\section fsk_page_sec_3 The receiver
54
55 The FSK receiver uses a quadrature correlation technique to demodulate the
56 signal. Two DDS quadrature oscillators are used. The incoming signal is
57 correlated with the oscillator signals over a period of one symbol. The
58 oscillator giving the highest net correlation from its I and Q outputs is the
59 one that matches the frequency being transmitted during the correlation
60 interval. Because the transmission is totally asynchronous, the demodulation
61 process must run sample by sample to find the symbol transitions. The
62 correlation is performed on a sliding window basis, so the computational load of
63 demodulating sample by sample is not great.
64
65 Two modes of symbol synchronisation are provided:
66
67 - In synchronous mode, symbol transitions are smoothed, to track their true
68 position in the prescence of high timing jitter. This provides the most
69 reliable symbol recovery in poor signal to noise conditions. However, it
70 takes a little time to settle, so it not really suitable for data streams
71 which must start up instantaneously (e.g. the TDD systems used by hearing
72 impaired people).
73
74 - In asynchronous mode each transition is taken at face value, with no temporal
75 smoothing. There is no settling time for this mode, but when the signal to
76 noise ratio is very poor it does not perform as well as the synchronous mode.
77*/
78
79#if !defined(_SPANDSP_FSK_H_)
80#define _SPANDSP_FSK_H_
81
82/*!
83 FSK modem specification. This defines the frequencies, signal levels and
84 baud rate (== bit rate for simple FSK) for a single channel of an FSK modem.
85*/
86 typedef struct
87{
88 /*! Short text name for the modem. */
89 const char *name;
90 /*! The frequency of the zero bit state, in Hz */
91 int freq_zero;
92 /*! The frequency of the one bit state, in Hz */
93 int freq_one;
94 /*! The transmit power level, in dBm0 */
95 int tx_level;
96 /*! The minimum acceptable receive power level, in dBm0 */
97 int min_level;
98 /*! The bit rate of the modem, in units of 1/100th bps */
99 int baud_rate;
100} fsk_spec_t;
101
102/* Predefined FSK modem channels */
103 enum
104{
105 FSK_V21CH1 = 0,
106 FSK_V21CH2,
107 FSK_V23CH1,
108 FSK_V23CH2,
109 FSK_BELL103CH1,
110 FSK_BELL103CH2,
111 FSK_BELL202,
112 FSK_WEITBRECHT, /* 45.45 baud version, used for TDD (Telecom Device for the Deaf) */
113 FSK_WEITBRECHT50, /* 50 baud version, used for TDD (Telecom Device for the Deaf) */
114 FSK_V21CH1_110 /* 110 bps version of V.21 channel 1, as used by V.18 */
115};
116
117 enum
118{
119 FSK_FRAME_MODE_ASYNC = 0,
120 FSK_FRAME_MODE_SYNC = 1,
121 FSK_FRAME_MODE_5N1_FRAMES = 7, /* 5 bits of data + start bit + stop bit */
122 FSK_FRAME_MODE_7N1_FRAMES = 9, /* 7 bits of data + start bit + stop bit */
123 FSK_FRAME_MODE_7E1_FRAMES = 10, /* 7 bits of data + even parity + start bit + stop bit */
124 FSK_FRAME_MODE_7E2_FRAMES = 11 /* 7 bits of data + even parity + start bit + 2 stop bits */
125};
126
127SPAN_DECLARE_DATA extern const fsk_spec_t preset_fsk_specs[];
128
129/*!
130 FSK modem transmit descriptor. This defines the state of a single working
131 instance of an FSK modem transmitter.
132*/
133 typedef struct fsk_tx_state_s fsk_tx_state_t;
134
135/* The longest window will probably be 106 for 75 baud */
136#define FSK_MAX_WINDOW_LEN 128
137
138/*!
139 FSK modem receive descriptor. This defines the state of a single working
140 instance of an FSK modem receiver.
141*/
142 typedef struct fsk_rx_state_s fsk_rx_state_t;
143
144#if defined(__cplusplus)
145 extern "C"
146{
147#endif
148
149/*! Initialise an FSK modem transmit context.
150 \brief Initialise an FSK modem transmit context.
151 \param s The modem context.
152 \param spec The specification of the modem tones and rate.
153 \param get_bit The callback routine used to get the data to be transmitted.
154 \param user_data An opaque pointer.
155 \return A pointer to the modem context, or NULL if there was a problem. */
156SPAN_DECLARE(fsk_tx_state_t *) fsk_tx_init(fsk_tx_state_t *s,
157 const fsk_spec_t *spec,
158 get_bit_func_t get_bit,
159 void *user_data);
160
161SPAN_DECLARE(int) fsk_tx_restart(fsk_tx_state_t *s, const fsk_spec_t *spec);
162
163SPAN_DECLARE(int) fsk_tx_release(fsk_tx_state_t *s);
164
165SPAN_DECLARE(int) fsk_tx_free(fsk_tx_state_t *s);
166
167/*! Adjust an FSK modem transmit context's power output.
168 \brief Adjust an FSK modem transmit context's power output.
169 \param s The modem context.
170 \param power The power level, in dBm0 */
171SPAN_DECLARE(void) fsk_tx_power(fsk_tx_state_t *s, float power);
172
173SPAN_DECLARE(void) fsk_tx_set_get_bit(fsk_tx_state_t *s, get_bit_func_t get_bit, void *user_data);
174
175/*! Change the modem status report function associated with an FSK modem transmit context.
176 \brief Change the modem status report function associated with an FSK modem transmit context.
177 \param s The modem context.
178 \param handler The callback routine used to report modem status changes.
179 \param user_data An opaque pointer. */
180SPAN_DECLARE(void) fsk_tx_set_modem_status_handler(fsk_tx_state_t *s, modem_status_func_t handler, void *user_data);
181
182/*! Generate a block of FSK modem audio samples.
183 \brief Generate a block of FSK modem audio samples.
184 \param s The modem context.
185 \param amp The audio sample buffer.
186 \param len The number of samples to be generated.
187 \return The number of samples actually generated.
188*/
189 SPAN_DECLARE_NONSTD(int) fsk_tx(fsk_tx_state_t *s, int16_t amp[], int len);
190
191/*! Get the current received signal power.
192 \param s The modem context.
193 \return The signal power, in dBm0. */
194SPAN_DECLARE(float) fsk_rx_signal_power(fsk_rx_state_t *s);
195
196/*! Adjust an FSK modem receive context's carrier detect power threshold.
197 \brief Adjust an FSK modem receive context's carrier detect power threshold.
198 \param s The modem context.
199 \param cutoff The power level, in dBm0 */
200SPAN_DECLARE(void) fsk_rx_signal_cutoff(fsk_rx_state_t *s, float cutoff);
201
202/*! Initialise an FSK modem receive context.
203 \brief Initialise an FSK modem receive context.
204 \param s The modem context.
205 \param spec The specification of the modem tones and rate.
206 \param framing_mode 0 for fully asynchronous mode. 1 for synchronous mode. >1 for
207 this many bits per asynchronous character frame.
208 \param put_bit The callback routine used to put the received data.
209 \param user_data An opaque pointer.
210 \return A pointer to the modem context, or NULL if there was a problem. */
211SPAN_DECLARE(fsk_rx_state_t *) fsk_rx_init(fsk_rx_state_t *s,
212 const fsk_spec_t *spec,
213 int framing_mode,
214 put_bit_func_t put_bit,
215 void *user_data);
216
217SPAN_DECLARE(int) fsk_rx_restart(fsk_rx_state_t *s, const fsk_spec_t *spec, int framing_mode);
218
219SPAN_DECLARE(int) fsk_rx_release(fsk_rx_state_t *s);
220
221SPAN_DECLARE(int) fsk_rx_free(fsk_rx_state_t *s);
222
223/*! Process a block of received FSK modem audio samples.
224 \brief Process a block of received FSK modem audio samples.
225 \param s The modem context.
226 \param amp The audio sample buffer.
227 \param len The number of samples in the buffer.
228 \return The number of samples unprocessed.
229*/
230 SPAN_DECLARE_NONSTD(int) fsk_rx(fsk_rx_state_t *s, const int16_t *amp, int len);
231
232/*! Fake processing of a missing block of received FSK modem audio samples
233 (e.g due to packet loss).
234 \brief Fake processing of a missing block of received FSK modem audio samples.
235 \param s The modem context.
236 \param len The number of samples to fake.
237 \return The number of samples unprocessed.
238*/
239 SPAN_DECLARE_NONSTD(int) fsk_rx_fillin(fsk_rx_state_t *s, int len);
240
241SPAN_DECLARE(void) fsk_rx_set_put_bit(fsk_rx_state_t *s, put_bit_func_t put_bit, void *user_data);
242
243/*! Change the modem status report function associated with an FSK modem receive context.
244 \brief Change the modem status report function associated with an FSK modem receive context.
245 \param s The modem context.
246 \param handler The callback routine used to report modem status changes.
247 \param user_data An opaque pointer. */
248SPAN_DECLARE(void) fsk_rx_set_modem_status_handler(fsk_rx_state_t *s, modem_status_func_t handler, void *user_data);
249
250#if defined(__cplusplus)
251}
252#endif
253
254#endif
255/*- End of file ------------------------------------------------------------*/
modem_status_func_t
void(* modem_status_func_t)(void *user_data, int status)
Definition async.h:114
put_bit_func_t
void(* put_bit_func_t)(void *user_data, int bit)
Definition async.h:105
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(void) async_rx_put_bit(void *user_data
Accept a bit from a received serial bit stream.
get_bit_func_t
int(* get_bit_func_t)(void *user_data)
Definition async.h:108
fsk_rx_state_t
struct fsk_rx_state_s fsk_rx_state_t
Definition fsk.h:142
fsk_rx_set_modem_status_handler
void fsk_rx_set_modem_status_handler(fsk_rx_state_t *s, modem_status_func_t handler, void *user_data)
Change the modem status report function associated with an FSK modem receive context.
Definition fsk.c:259
fsk_tx_set_modem_status_handler
void fsk_tx_set_modem_status_handler(fsk_tx_state_t *s, modem_status_func_t handler, void *user_data)
Change the modem status report function associated with an FSK modem transmit context.
Definition fsk.c:231
fsk_rx_init
fsk_rx_state_t * fsk_rx_init(fsk_rx_state_t *s, const fsk_spec_t *spec, int framing_mode, put_bit_func_t put_bit, void *user_data)
Initialise an FSK modem receive context.
Definition fsk.c:314
fsk_rx_signal_power
float fsk_rx_signal_power(fsk_rx_state_t *s)
Definition fsk.c:246
fsk_rx_signal_cutoff
void fsk_rx_signal_cutoff(fsk_rx_state_t *s, float cutoff)
Adjust an FSK modem receive context's carrier detect power threshold.
Definition fsk.c:238
fsk_tx_init
fsk_tx_state_t * fsk_tx_init(fsk_tx_state_t *s, const fsk_spec_t *spec, get_bit_func_t get_bit, void *user_data)
Initialise an FSK modem transmit context.
Definition fsk.c:153
fsk_tx_state_t
struct fsk_tx_state_s fsk_tx_state_t
Definition fsk.h:133
fsk_tx_power
void fsk_tx_power(fsk_tx_state_t *s, float power)
Adjust an FSK modem transmit context's power output.
Definition fsk.c:218
fsk_rx_state_s
Definition private/fsk.h:59
fsk_rx_state_s::framing_mode
int framing_mode
Synchronous/asynchronous framing control.
Definition private/fsk.h:62
fsk_spec_t
Definition fsk.h:87
fsk_spec_t::freq_one
int freq_one
Definition fsk.h:93
fsk_spec_t::name
const char * name
Definition fsk.h:89
fsk_spec_t::tx_level
int tx_level
Definition fsk.h:95
fsk_spec_t::min_level
int min_level
Definition fsk.h:97
fsk_spec_t::baud_rate
int baud_rate
Definition fsk.h:99
fsk_spec_t::freq_zero
int freq_zero
Definition fsk.h:91
fsk_tx_state_s
Definition private/fsk.h:34