-
Notifications
You must be signed in to change notification settings - Fork 133
/
freedv_api.h
311 lines (257 loc) · 14 KB
/
freedv_api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
/*---------------------------------------------------------------------------*\
FILE........: freedv_api.h
AUTHOR......: David Rowe
DATE CREATED: August 2014
Library of API functions that implement the FreeDV API, useful for
embedding FreeDV in other programs. Please see:
1. README_freedv.md
2. Notes on function use in freedv_api.c
3. Simple demo programs in the "demo" directory
4. The full featured command line freedv_tx.c and freedv_rx.c programs
\*---------------------------------------------------------------------------*/
/*
Copyright (C) 2014 David Rowe
All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License version 2.1, as
published by the Free Software Foundation. This program is
distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program; if not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __FREEDV_API__
#define __FREEDV_API__
#include <sys/types.h>
#include <stdbool.h>
// This declares a single-precision (float) complex number
#include "comp.h"
#ifdef __cplusplus
extern "C" {
#endif
// available speech modes
#define FREEDV_MODE_1600 0
#define FREEDV_MODE_2400A 3
#define FREEDV_MODE_2400B 4
#define FREEDV_MODE_800XA 5
#define FREEDV_MODE_700C 6
#define FREEDV_MODE_700D 7
#define FREEDV_MODE_700E 13
#define FREEDV_MODE_2020 8
#define FREEDV_MODE_2020B 16
#define FREEDV_MODE_2020C 17
// available data modes
#define FREEDV_MODE_FSK_LDPC 9
#define FREEDV_MODE_DATAC1 10
#define FREEDV_MODE_DATAC3 12
#define FREEDV_MODE_DATAC0 14
#define FREEDV_MODE_DATAC4 18
#define FREEDV_MODE_DATAC13 19
// Sample rates used
#define FREEDV_FS_8000 8000
#define FREEDV_FS_16000 16000
// peak (complex) sample value from Tx modulator
#define FREEDV_PEAK 16384
// Return code flags for freedv_get_rx_status() function
#define FREEDV_RX_TRIAL_SYNC 0x1 // demodulator has trial sync
#define FREEDV_RX_SYNC 0x2 // demodulator has sync
#define FREEDV_RX_BITS 0x4 // data bits have been returned
#define FREEDV_RX_BIT_ERRORS 0x8 // FEC may not have corrected all bit errors (not all parity checks OK)
// optional operator control of OFDM modem state machine
#define FREEDV_SYNC_UNSYNC 0 // force sync state machine to lose sync, and search for new sync
#define FREEDV_SYNC_AUTO 1 // falls out of sync automatically
#define FREEDV_SYNC_MANUAL 2 // fall out of sync only under operator control
#define FREEDV_VARICODE_MAX_BITS 12 // max bits for each ASCII character
// These macros allow us to disable unwanted modes at compile tine, for example
// to save memory on embedded systems or the remove need to link other
// libraries. By default we enable all modes. Disable during compile time e.g
// -DFREEDV_MODE_1600_EN=0 will enable all but FreeDV 1600. Or the other way
// round -DFREEDV_MODE_EN_DEFAULT=0 -DFREEDV_MODE_1600_EN=1 will enable only
// FreeDV 1600
#ifndef FREEDV_MODE_EN_DEFAULT
#define FREEDV_MODE_EN_DEFAULT 1
#endif
#if !defined(FREEDV_MODE_1600_EN)
#define FREEDV_MODE_1600_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_700C_EN)
#define FREEDV_MODE_700C_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_700D_EN)
#define FREEDV_MODE_700D_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_700E_EN)
#define FREEDV_MODE_700E_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_2400A_EN)
#define FREEDV_MODE_2400A_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_2400B_EN)
#define FREEDV_MODE_2400B_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_800XA_EN)
#define FREEDV_MODE_800XA_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_2020_EN)
#define FREEDV_MODE_2020_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_2020B_EN)
#define FREEDV_MODE_2020B_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_2020C_EN)
#define FREEDV_MODE_2020C_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_FSK_LDPC_EN)
#define FREEDV_MODE_FSK_LDPC_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_DATAC0_EN)
#define FREEDV_MODE_DATAC0_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_DATAC1_EN)
#define FREEDV_MODE_DATAC1_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_DATAC3_EN)
#define FREEDV_MODE_DATAC3_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_DATAC4_EN)
#define FREEDV_MODE_DATAC4_EN FREEDV_MODE_EN_DEFAULT
#endif
#if !defined(FREEDV_MODE_DATAC13_EN)
#define FREEDV_MODE_DATAC13_EN FREEDV_MODE_EN_DEFAULT
#endif
#define FDV_MODE_ACTIVE(mode_name, var) ((mode_name##_EN) == 0 ? 0: (var) == mode_name)
// struct that hold state information for one freedv instance
struct freedv;
// Some modes allow extra configuration parameters
struct freedv_advanced {
int interleave_frames; // now unused but remains to prevent breaking API for legacy apps
// parameters for FREEDV_MODE_FSK_LDPC
int M; // 2 or 4 FSK
int Rs; // Symbol rate Hz
int Fs; // Sample rate Hz
int first_tone; // Freq of first tone Hz
int tone_spacing; // Spacing between tones Hz
char *codename; // LDPC codename, from codes listed in ldpc_codes.c
};
// Called when text message char is decoded
typedef void (*freedv_callback_rx)(void *, char);
// Called when new text message char is needed
typedef char (*freedv_callback_tx)(void *);
typedef void (*freedv_calback_error_pattern)
(void *error_pattern_callback_state, short error_pattern[], int sz_error_pattern);
// Protocol bits are packed MSB-first
// Called when a frame containing protocol data is decoded
typedef void (*freedv_callback_protorx)(void *, char *);
// Called when a frame containing protocol data is to be sent
typedef void (*freedv_callback_prototx)(void *, char *);
// Data packet callbacks
// Called when a packet has been received
typedef void (*freedv_callback_datarx)(void *, unsigned char *packet, size_t size);
// Called when a new packet can be send
typedef void (*freedv_callback_datatx)(void *, unsigned char *packet, size_t *size);
/*---------------------------------------------------------------------------*\
FreeDV API functions
\*---------------------------------------------------------------------------*/
// open, close ----------------------------------------------------------------
struct freedv *freedv_open_advanced(int mode, struct freedv_advanced *adv);
struct freedv *freedv_open(int mode);
void freedv_close (struct freedv *freedv);
// Transmit -------------------------------------------------------------------
void freedv_tx (struct freedv *freedv, short mod_out[], short speech_in[]);
void freedv_comptx (struct freedv *freedv, COMP mod_out[], short speech_in[]);
void freedv_datatx (struct freedv *f, short mod_out[]);
int freedv_data_ntxframes (struct freedv *freedv);
void freedv_rawdatatx (struct freedv *f, short mod_out[], unsigned char *packed_payload_bits);
void freedv_rawdatacomptx (struct freedv *f, COMP mod_out[], unsigned char *packed_payload_bits);
int freedv_rawdatapreambletx (struct freedv *f, short mod_out[]);
int freedv_rawdatapreamblecomptx (struct freedv *f, COMP mod_out[]);
int freedv_rawdatapostambletx (struct freedv *f, short mod_out[]);
int freedv_rawdatapostamblecomptx (struct freedv *f, COMP mod_out[]);
// Receive -------------------------------------------------------------------
int freedv_nin (struct freedv *freedv);
int freedv_rx (struct freedv *freedv, short speech_out[], short demod_in[]);
int freedv_shortrx (struct freedv *freedv, short speech_out[], short demod_in[], float gain);
int freedv_floatrx (struct freedv *freedv, short speech_out[], float demod_in[]);
int freedv_comprx (struct freedv *freedv, short speech_out[], COMP demod_in[]);
int freedv_rawdatarx (struct freedv *freedv, unsigned char *packed_payload_bits, short demod_in[]);
int freedv_rawdatacomprx (struct freedv *freedv, unsigned char *packed_payload_bits, COMP demod_in[]);
// Helper functions -------------------------------------------------------------------
int freedv_codec_frames_from_rawdata(struct freedv *freedv, unsigned char *codec_frames, unsigned char *rawdata);
int freedv_rawdata_from_codec_frames(struct freedv *freedv, unsigned char *rawdata, unsigned char *codec_frames);
unsigned short freedv_gen_crc16(unsigned char* bytes, int nbytes);
void freedv_pack(unsigned char *bytes, unsigned char *bits, int nbits);
void freedv_unpack(unsigned char *bits, unsigned char *bytes, int nbits);
unsigned short freedv_crc16_unpacked(unsigned char *bits, int nbits);
int freedv_check_crc16_unpacked(unsigned char *unpacked_bits, int nbits);
// Set parameters ------------------------------------------------------------
void freedv_set_callback_txt (struct freedv *freedv, freedv_callback_rx rx, freedv_callback_tx tx, void *callback_state);
void freedv_set_callback_protocol (struct freedv *freedv, freedv_callback_protorx rx, freedv_callback_prototx tx, void *callback_state);
void freedv_set_callback_data (struct freedv *freedv, freedv_callback_datarx datarx, freedv_callback_datatx datatx, void *callback_state);
void freedv_set_test_frames (struct freedv *freedv, int test_frames);
void freedv_set_test_frames_diversity (struct freedv *freedv, int test_frames_diversity);
void freedv_set_smooth_symbols (struct freedv *freedv, int smooth_symbols);
void freedv_set_squelch_en (struct freedv *freedv, bool squelch_en);
void freedv_set_snr_squelch_thresh (struct freedv *freedv, float snr_squelch_thresh);
void freedv_set_clip (struct freedv *freedv, bool val);
void freedv_set_total_bit_errors (struct freedv *freedv, int val);
void freedv_set_total_bits (struct freedv *freedv, int val);
void freedv_set_total_bit_errors_coded (struct freedv *freedv, int val);
void freedv_set_total_bits_coded (struct freedv *freedv, int val);
void freedv_set_total_packets (struct freedv *freedv, int val);
void freedv_set_total_packet_errors (struct freedv *freedv, int val);
void freedv_set_callback_error_pattern (struct freedv *freedv, freedv_calback_error_pattern cb, void *state);
void freedv_set_varicode_code_num (struct freedv *freedv, int val);
void freedv_set_data_header (struct freedv *freedv, unsigned char *header);
void freedv_set_carrier_ampl (struct freedv *freedv, int c, float ampl);
void freedv_set_sync (struct freedv *freedv, int sync_cmd);
void freedv_set_verbose (struct freedv *freedv, int verbosity);
void freedv_set_tx_bpf (struct freedv *freedv, int val);
void freedv_set_tx_amp (struct freedv *freedv, float amp);
void freedv_set_ext_vco (struct freedv *f, int val);
void freedv_set_phase_est_bandwidth_mode(struct freedv *f, int val);
void freedv_set_eq (struct freedv *f, bool val);
void freedv_set_frames_per_burst (struct freedv *f, int framesperburst);
void freedv_passthrough_gain (struct freedv *f, float g);
int freedv_set_tuning_range (struct freedv *freedv, float val_fmin, float val_fmax);
// Get parameters -------------------------------------------------------------------------
struct MODEM_STATS;
int freedv_get_version(void);
char *freedv_get_hash(void);
int freedv_get_mode (struct freedv *freedv);
void freedv_get_modem_stats (struct freedv *freedv, int *sync, float *snr_est);
void freedv_get_modem_extended_stats(struct freedv *freedv, struct MODEM_STATS *stats);
int freedv_get_test_frames (struct freedv *freedv);
int freedv_get_speech_sample_rate (struct freedv *freedv);
int freedv_get_n_speech_samples (struct freedv *freedv);
int freedv_get_n_max_speech_samples (struct freedv *freedv);
int freedv_get_modem_sample_rate (struct freedv *freedv);
int freedv_get_modem_symbol_rate (struct freedv *freedv);
int freedv_get_n_max_modem_samples (struct freedv *freedv);
int freedv_get_n_nom_modem_samples (struct freedv *freedv);
int freedv_get_n_tx_modem_samples (struct freedv *freedv);
int freedv_get_n_tx_preamble_modem_samples(struct freedv *freedv);
int freedv_get_n_tx_postamble_modem_samples(struct freedv *freedv);
// bit error rate stats
int freedv_get_total_bits (struct freedv *freedv);
int freedv_get_total_bit_errors (struct freedv *freedv);
int freedv_get_total_bits_coded (struct freedv *freedv);
int freedv_get_total_bit_errors_coded (struct freedv *freedv);
int freedv_get_total_packets (struct freedv *freedv);
int freedv_get_total_packet_errors (struct freedv *freedv);
int freedv_get_rx_status (struct freedv *freedv);
void freedv_get_fsk_S_and_N (struct freedv *freedv, float *S, float *N);
int freedv_get_sync (struct freedv *freedv);
int freedv_get_sync_interleaver (struct freedv *freedv);
// access to speech codec states
struct FSK * freedv_get_fsk (struct freedv *f);
struct CODEC2 *freedv_get_codec2 (struct freedv *freedv);
int freedv_get_bits_per_codec_frame (struct freedv *freedv);
int freedv_get_bits_per_modem_frame (struct freedv *freedv);
int freedv_get_sz_error_pattern (struct freedv *freedv);
int freedv_get_protocol_bits (struct freedv *freedv);
#ifdef __cplusplus
}
#endif
#endif //__FREEDV_API__