spandsp  3.0.0
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 Three 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  - In framed mode a soft decode of the bit stream occurs, which is more noise
79  tolerant than the asynchronous mode. This outputs fully decoded start-stop
80  framed characters, which have been parity checked. There is no option for
81  V.14 rate adaption, as this is not relevant for the truly asynchronous FSK
82  modems supported by this module.
83 */
84 
85 #if !defined(_SPANDSP_FSK_H_)
86 #define _SPANDSP_FSK_H_
87 
88 /*!
89  FSK modem specification. This defines the frequencies, signal levels and
90  baud rate (== bit rate for simple FSK) for a single channel of an FSK modem.
91 */
92 typedef struct
93 {
94  /*! Short text name for the modem. */
95  const char *name;
96  /*! The frequency of the zero bit state, in Hz */
97  int freq_zero;
98  /*! The frequency of the one bit state, in Hz */
99  int freq_one;
100  /*! The transmit power level, in dBm0 */
101  int tx_level;
102  /*! The minimum acceptable receive power level, in dBm0 */
104  /*! The bit rate of the modem, in units of 1/100th bps */
106 } fsk_spec_t;
107 
108 /* Predefined FSK modem channels */
109 enum
110 {
111  FSK_V21CH1 = 0,
112  FSK_V21CH2,
113  FSK_V23CH1,
114  FSK_V23CH2,
115  FSK_BELL103CH1,
116  FSK_BELL103CH2,
117  FSK_BELL202,
118  FSK_WEITBRECHT_4545, /* 45.45 baud version, used for TDD (Telecom Device for the Deaf) */
119  FSK_WEITBRECHT_50, /* 50 baud version, used for TDD (Telecom Device for the Deaf) */
120  FSK_WEITBRECHT_476, /* 47.6 baud version, used for V.18 probing */
121  FSK_V21CH1_110 /* 110 bps version of V.21 channel 1, as used by V.18 */
122 };
123 
124 enum
125 {
126  FSK_FRAME_MODE_ASYNC = 0,
127  FSK_FRAME_MODE_SYNC = 1,
128  FSK_FRAME_MODE_FRAMED = 2
129 };
130 
131 SPAN_DECLARE_DATA extern const fsk_spec_t preset_fsk_specs[];
132 
133 /*!
134  FSK modem transmit descriptor. This defines the state of a single working
135  instance of an FSK modem transmitter.
136 */
138 
139 /* The longest window will probably be 106 for 75 baud */
140 #define FSK_MAX_WINDOW_LEN 128
141 
142 /*!
143  FSK modem receive descriptor. This defines the state of a single working
144  instance of an FSK modem receiver.
145 */
147 
148 #if defined(__cplusplus)
149 extern "C"
150 {
151 #endif
152 
153 /*! Initialise an FSK modem transmit context.
154  \brief Initialise an FSK modem transmit context.
155  \param s The modem context.
156  \param spec The specification of the modem tones and rate.
157  \param get_bit The callback routine used to get the data to be transmitted.
158  \param user_data An opaque pointer.
159  \return A pointer to the modem context, or NULL if there was a problem. */
160 SPAN_DECLARE(fsk_tx_state_t *) fsk_tx_init(fsk_tx_state_t *s,
161  const fsk_spec_t *spec,
162  span_get_bit_func_t get_bit,
163  void *user_data);
164 
165 SPAN_DECLARE(int) fsk_tx_restart(fsk_tx_state_t *s, const fsk_spec_t *spec);
166 
167 SPAN_DECLARE(int) fsk_tx_release(fsk_tx_state_t *s);
168 
169 SPAN_DECLARE(int) fsk_tx_free(fsk_tx_state_t *s);
170 
171 /*! Adjust an FSK modem transmit context's power output.
172  \brief Adjust an FSK modem transmit context's power output.
173  \param s The modem context.
174  \param power The power level, in dBm0 */
175 SPAN_DECLARE(void) fsk_tx_power(fsk_tx_state_t *s, float power);
176 
177 SPAN_DECLARE(void) fsk_tx_set_get_bit(fsk_tx_state_t *s, span_get_bit_func_t get_bit, void *user_data);
178 
179 /*! Change the modem status report function associated with an FSK modem transmit context.
180  \brief Change the modem status report function associated with an FSK modem transmit context.
181  \param s The modem context.
182  \param handler The callback routine used to report modem status changes.
183  \param user_data An opaque pointer. */
184 SPAN_DECLARE(void) fsk_tx_set_modem_status_handler(fsk_tx_state_t *s, span_modem_status_func_t handler, void *user_data);
185 
186 /*! Generate a block of FSK modem audio samples.
187  \brief Generate a block of FSK modem audio samples.
188  \param s The modem context.
189  \param amp The audio sample buffer.
190  \param len The number of samples to be generated.
191  \return The number of samples actually generated.
192 */
193 SPAN_DECLARE(int) fsk_tx(fsk_tx_state_t *s, int16_t amp[], int len);
194 
195 /*! Get the current received signal power.
196  \param s The modem context.
197  \return The signal power, in dBm0. */
198 SPAN_DECLARE(float) fsk_rx_signal_power(fsk_rx_state_t *s);
199 
200 /*! Adjust an FSK modem receive context's carrier detect power threshold.
201  \brief Adjust an FSK modem receive context's carrier detect power threshold.
202  \param s The modem context.
203  \param cutoff The power level, in dBm0 */
204 SPAN_DECLARE(void) fsk_rx_set_signal_cutoff(fsk_rx_state_t *s, float cutoff);
205 
206 /*! Set the framing parameters for a an FSK modem receive context in
207  FSK_FRAME_MODE_FRAMED mode.
208  \brief Set the framing parameters.
209  \param s The modem context.
210  \param data_bits;
211  \param parity;
212  \param stop_bits; */
213 SPAN_DECLARE(void) fsk_rx_set_frame_parameters(fsk_rx_state_t *s,
214  int data_bits,
215  int parity,
216  int stop_bits);
217 
218 SPAN_DECLARE(int) fsk_rx_get_parity_errors(fsk_rx_state_t *s, bool reset);
219 
220 SPAN_DECLARE(int) fsk_rx_get_framing_errors(fsk_rx_state_t *s, bool reset);
221 
222 /*! Initialise an FSK modem receive context.
223  \brief Initialise an FSK modem receive context.
224  \param s The modem context.
225  \param spec The specification of the modem tones and rate.
226  \param framing_mode
227  \param put_bit The callback routine used to put the received data.
228  \param user_data An opaque pointer.
229  \return A pointer to the modem context, or NULL if there was a problem. */
230 SPAN_DECLARE(fsk_rx_state_t *) fsk_rx_init(fsk_rx_state_t *s,
231  const fsk_spec_t *spec,
232  int framing_mode,
234  void *user_data);
235 
236 SPAN_DECLARE(int) fsk_rx_restart(fsk_rx_state_t *s,
237  const fsk_spec_t *spec,
238  int framing_mode);
239 
240 SPAN_DECLARE(int) fsk_rx_release(fsk_rx_state_t *s);
241 
242 SPAN_DECLARE(int) fsk_rx_free(fsk_rx_state_t *s);
243 
244 /*! Process a block of received FSK modem audio samples.
245  \brief Process a block of received FSK modem audio samples.
246  \param s The modem context.
247  \param amp The audio sample buffer.
248  \param len The number of samples in the buffer.
249  \return The number of samples unprocessed.
250 */
251 SPAN_DECLARE(int) fsk_rx(fsk_rx_state_t *s, const int16_t *amp, int len);
252 
253 /*! Fake processing of a missing block of received FSK modem audio samples
254  (e.g due to packet loss).
255  \brief Fake processing of a missing block of received FSK modem audio samples.
256  \param s The modem context.
257  \param len The number of samples to fake.
258  \return The number of samples unprocessed.
259 */
260 SPAN_DECLARE(int) fsk_rx_fillin(fsk_rx_state_t *s, int len);
261 
262 SPAN_DECLARE(void) fsk_rx_set_put_bit(fsk_rx_state_t *s, span_put_bit_func_t put_bit, void *user_data);
263 
264 /*! Change the modem status report function associated with an FSK modem receive context.
265  \brief Change the modem status report function associated with an FSK modem receive context.
266  \param s The modem context.
267  \param handler The callback routine used to report modem status changes.
268  \param user_data An opaque pointer. */
269 SPAN_DECLARE(void) fsk_rx_set_modem_status_handler(fsk_rx_state_t *s, span_modem_status_func_t handler, void *user_data);
270 
271 #if defined(__cplusplus)
272 }
273 #endif
274 
275 #endif
276 /*- End of file ------------------------------------------------------------*/
int freq_one
Definition: fsk.h:99
void fsk_tx_power(fsk_tx_state_t *s, float power)
Adjust an FSK modem transmit context&#39;s power output.
Definition: fsk.c:201
fsk_tx_state_t * fsk_tx_init(fsk_tx_state_t *s, const fsk_spec_t *spec, span_get_bit_func_t get_bit, void *user_data)
Initialise an FSK modem transmit context.
Definition: fsk.c:237
int min_level
Definition: fsk.h:103
int fsk_rx(fsk_rx_state_t *s, const int16_t *amp, int len)
Process a block of received FSK modem audio samples.
Definition: fsk.c:396
fsk_rx_state_t * fsk_rx_init(fsk_rx_state_t *s, const fsk_spec_t *spec, int framing_mode, span_put_bit_func_t put_bit, void *user_data)
Initialise an FSK modem receive context.
Definition: fsk.c:725
int(* span_get_bit_func_t)(void *user_data)
Definition: async.h:127
int framing_mode
Synchronous/asynchronous/framed control.
Definition: private/fsk.h:62
Definition: private/fsk.h:58
void(* span_modem_status_func_t)(void *user_data, int status)
Definition: async.h:131
void(* span_put_bit_func_t)(void *user_data, int bit)
Definition: async.h:123
Definition: private/fsk.h:33
int baud_rate
Definition: fsk.h:105
void fsk_rx_set_frame_parameters(fsk_rx_state_t *s, int data_bits, int parity, int stop_bits)
Set the framing parameters.
Definition: fsk.c:300
const char * name
Definition: fsk.h:95
int tx_level
Definition: fsk.h:101
Definition: fsk.h:92
float fsk_rx_signal_power(fsk_rx_state_t *s)
Definition: fsk.c:280
void fsk_rx_set_signal_cutoff(fsk_rx_state_t *s, float cutoff)
Adjust an FSK modem receive context&#39;s carrier detect power threshold.
Definition: fsk.c:271
int fsk_tx(fsk_tx_state_t *s, int16_t amp[], int len)
Generate a block of FSK modem audio samples.
Definition: fsk.c:162
void fsk_tx_set_modem_status_handler(fsk_tx_state_t *s, span_modem_status_func_t handler, void *user_data)
Change the modem status report function associated with an FSK modem transmit context.
Definition: fsk.c:214
int freq_zero
Definition: fsk.h:97
int fsk_rx_fillin(fsk_rx_state_t *s, int len)
Fake processing of a missing block of received FSK modem audio samples.
Definition: fsk.c:637
span_put_bit_func_t put_bit
The callback function used to put each bit received.
Definition: private/fsk.h:68
void fsk_rx_set_modem_status_handler(fsk_rx_state_t *s, span_modem_status_func_t handler, void *user_data)
Change the modem status report function associated with an FSK modem receive context.
Definition: fsk.c:293