75bfd3fda7e50f2dc33eb22fb2ec261dd46ab1fb
[rtl-433.git] / include / rtl-sdr.h
1 /*
2  * rtl-sdr, turns your Realtek RTL2832 based DVB dongle into a SDR receiver
3  * Copyright (C) 2012 by Steve Markgraf <steve@steve-m.de>
4  * Copyright (C) 2012 by Dimitri Stolnikov <horiz0n@gmx.net>
5  *
6  * This program is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 #ifndef __RTL_SDR_H
21 #define __RTL_SDR_H
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 #include <stdint.h>
28 #include <rtl-sdr_export.h>
29
30 typedef struct rtlsdr_dev rtlsdr_dev_t;
31
32 RTLSDR_API uint32_t rtlsdr_get_device_count(void);
33
34 RTLSDR_API const char* rtlsdr_get_device_name(uint32_t index);
35
36 /*!
37  * Get USB device strings.
38  *
39  * NOTE: The string arguments must provide space for up to 256 bytes.
40  *
41  * \param index the device index
42  * \param manufact manufacturer name, may be NULL
43  * \param product product name, may be NULL
44  * \param serial serial number, may be NULL
45  * \return 0 on success
46  */
47 RTLSDR_API int rtlsdr_get_device_usb_strings(uint32_t index,
48                                              char *manufact,
49                                              char *product,
50                                              char *serial);
51
52 /*!
53  * Get device index by USB serial string descriptor.
54  *
55  * \param serial serial string of the device
56  * \return device index of first device where the name matched
57  * \return -1 if name is NULL
58  * \return -2 if no devices were found at all
59  * \return -3 if devices were found, but none with matching name
60  */
61 RTLSDR_API int rtlsdr_get_index_by_serial(const char *serial);
62
63 RTLSDR_API int rtlsdr_open(rtlsdr_dev_t **dev, uint32_t index);
64
65 RTLSDR_API int rtlsdr_close(rtlsdr_dev_t *dev);
66
67 /* configuration functions */
68
69 /*!
70  * Set crystal oscillator frequencies used for the RTL2832 and the tuner IC.
71  *
72  * Usually both ICs use the same clock. Changing the clock may make sense if
73  * you are applying an external clock to the tuner or to compensate the
74  * frequency (and samplerate) error caused by the original (cheap) crystal.
75  *
76  * NOTE: Call this function only if you fully understand the implications.
77  *
78  * \param dev the device handle given by rtlsdr_open()
79  * \param rtl_freq frequency value used to clock the RTL2832 in Hz
80  * \param tuner_freq frequency value used to clock the tuner IC in Hz
81  * \return 0 on success
82  */
83 RTLSDR_API int rtlsdr_set_xtal_freq(rtlsdr_dev_t *dev, uint32_t rtl_freq,
84                                     uint32_t tuner_freq);
85
86 /*!
87  * Get crystal oscillator frequencies used for the RTL2832 and the tuner IC.
88  *
89  * Usually both ICs use the same clock.
90  *
91  * \param dev the device handle given by rtlsdr_open()
92  * \param rtl_freq frequency value used to clock the RTL2832 in Hz
93  * \param tuner_freq frequency value used to clock the tuner IC in Hz
94  * \return 0 on success
95  */
96 RTLSDR_API int rtlsdr_get_xtal_freq(rtlsdr_dev_t *dev, uint32_t *rtl_freq,
97                                     uint32_t *tuner_freq);
98
99 /*!
100  * Get USB device strings.
101  *
102  * NOTE: The string arguments must provide space for up to 256 bytes.
103  *
104  * \param dev the device handle given by rtlsdr_open()
105  * \param manufact manufacturer name, may be NULL
106  * \param product product name, may be NULL
107  * \param serial serial number, may be NULL
108  * \return 0 on success
109  */
110 RTLSDR_API int rtlsdr_get_usb_strings(rtlsdr_dev_t *dev, char *manufact,
111                                       char *product, char *serial);
112
113 /*!
114  * Write the device EEPROM
115  *
116  * \param dev the device handle given by rtlsdr_open()
117  * \param data buffer of data to be written
118  * \param offset address where the data should be written
119  * \param len length of the data
120  * \return 0 on success
121  * \return -1 if device handle is invalid
122  * \return -2 if EEPROM size is exceeded
123  * \return -3 if no EEPROM was found
124  */
125
126 RTLSDR_API int rtlsdr_write_eeprom(rtlsdr_dev_t *dev, uint8_t *data,
127                                   uint8_t offset, uint16_t len);
128
129 /*!
130  * Read the device EEPROM
131  *
132  * \param dev the device handle given by rtlsdr_open()
133  * \param data buffer where the data should be written
134  * \param offset address where the data should be read from
135  * \param len length of the data
136  * \return 0 on success
137  * \return -1 if device handle is invalid
138  * \return -2 if EEPROM size is exceeded
139  * \return -3 if no EEPROM was found
140  */
141
142 RTLSDR_API int rtlsdr_read_eeprom(rtlsdr_dev_t *dev, uint8_t *data,
143                                   uint8_t offset, uint16_t len);
144
145 RTLSDR_API int rtlsdr_set_center_freq(rtlsdr_dev_t *dev, uint32_t freq);
146
147 /*!
148  * Get actual frequency the device is tuned to.
149  *
150  * \param dev the device handle given by rtlsdr_open()
151  * \return 0 on error, frequency in Hz otherwise
152  */
153 RTLSDR_API uint32_t rtlsdr_get_center_freq(rtlsdr_dev_t *dev);
154
155 /*!
156  * Set the frequency correction value for the device.
157  *
158  * \param dev the device handle given by rtlsdr_open()
159  * \param ppm correction value in parts per million (ppm)
160  * \return 0 on success
161  */
162 RTLSDR_API int rtlsdr_set_freq_correction(rtlsdr_dev_t *dev, int ppm);
163
164 /*!
165  * Get actual frequency correction value of the device.
166  *
167  * \param dev the device handle given by rtlsdr_open()
168  * \return correction value in parts per million (ppm)
169  */
170 RTLSDR_API int rtlsdr_get_freq_correction(rtlsdr_dev_t *dev);
171
172 enum rtlsdr_tuner {
173         RTLSDR_TUNER_UNKNOWN = 0,
174         RTLSDR_TUNER_E4000,
175         RTLSDR_TUNER_FC0012,
176         RTLSDR_TUNER_FC0013,
177         RTLSDR_TUNER_FC2580,
178         RTLSDR_TUNER_R820T
179 };
180
181 /*!
182  * Get the tuner type.
183  *
184  * \param dev the device handle given by rtlsdr_open()
185  * \return RTLSDR_TUNER_UNKNOWN on error, tuner type otherwise
186  */
187 RTLSDR_API enum rtlsdr_tuner rtlsdr_get_tuner_type(rtlsdr_dev_t *dev);
188
189 /*!
190  * Get a list of gains supported by the tuner.
191  *
192  * NOTE: The gains argument must be preallocated by the caller. If NULL is
193  * being given instead, the number of available gain values will be returned.
194  *
195  * \param dev the device handle given by rtlsdr_open()
196  * \param gains array of gain values. In tenths of a dB, 115 means 11.5 dB.
197  * \return <= 0 on error, number of available (returned) gain values otherwise
198  */
199 RTLSDR_API int rtlsdr_get_tuner_gains(rtlsdr_dev_t *dev, int *gains);
200
201 /*!
202  * Set the gain for the device.
203  * Manual gain mode must be enabled for this to work.
204  *
205  * Valid gain values (in tenths of a dB) for the E4000 tuner:
206  * -10, 15, 40, 65, 90, 115, 140, 165, 190,
207  * 215, 240, 290, 340, 420, 430, 450, 470, 490
208  *
209  * Valid gain values may be queried with \ref rtlsdr_get_tuner_gains function.
210  *
211  * \param dev the device handle given by rtlsdr_open()
212  * \param gain in tenths of a dB, 115 means 11.5 dB.
213  * \return 0 on success
214  */
215 RTLSDR_API int rtlsdr_set_tuner_gain(rtlsdr_dev_t *dev, int gain);
216
217 /*!
218  * Get actual gain the device is configured to.
219  *
220  * \param dev the device handle given by rtlsdr_open()
221  * \return 0 on error, gain in tenths of a dB, 115 means 11.5 dB.
222  */
223 RTLSDR_API int rtlsdr_get_tuner_gain(rtlsdr_dev_t *dev);
224
225 /*!
226  * Set the intermediate frequency gain for the device.
227  *
228  * \param dev the device handle given by rtlsdr_open()
229  * \param stage intermediate frequency gain stage number (1 to 6 for E4000)
230  * \param gain in tenths of a dB, -30 means -3.0 dB.
231  * \return 0 on success
232  */
233 RTLSDR_API int rtlsdr_set_tuner_if_gain(rtlsdr_dev_t *dev, int stage, int gain);
234
235 /*!
236  * Set the gain mode (automatic/manual) for the device.
237  * Manual gain mode must be enabled for the gain setter function to work.
238  *
239  * \param dev the device handle given by rtlsdr_open()
240  * \param manual gain mode, 1 means manual gain mode shall be enabled.
241  * \return 0 on success
242  */
243 RTLSDR_API int rtlsdr_set_tuner_gain_mode(rtlsdr_dev_t *dev, int manual);
244
245 /* this will select the baseband filters according to the requested sample rate */
246 RTLSDR_API int rtlsdr_set_sample_rate(rtlsdr_dev_t *dev, uint32_t rate);
247
248 /*!
249  * Get actual sample rate the device is configured to.
250  *
251  * \param dev the device handle given by rtlsdr_open()
252  * \return 0 on error, sample rate in Hz otherwise
253  */
254 RTLSDR_API uint32_t rtlsdr_get_sample_rate(rtlsdr_dev_t *dev);
255
256 /*!
257  * Enable test mode that returns an 8 bit counter instead of the samples.
258  * The counter is generated inside the RTL2832.
259  *
260  * \param dev the device handle given by rtlsdr_open()
261  * \param test mode, 1 means enabled, 0 disabled
262  * \return 0 on success
263  */
264 RTLSDR_API int rtlsdr_set_testmode(rtlsdr_dev_t *dev, int on);
265
266 /*!
267  * Enable or disable the internal digital AGC of the RTL2832.
268  *
269  * \param dev the device handle given by rtlsdr_open()
270  * \param digital AGC mode, 1 means enabled, 0 disabled
271  * \return 0 on success
272  */
273 RTLSDR_API int rtlsdr_set_agc_mode(rtlsdr_dev_t *dev, int on);
274
275 /*!
276  * Enable or disable the direct sampling mode. When enabled, the IF mode
277  * of the RTL2832 is activated, and rtlsdr_set_center_freq() will control
278  * the IF-frequency of the DDC, which can be used to tune from 0 to 28.8 MHz
279  * (xtal frequency of the RTL2832).
280  *
281  * \param dev the device handle given by rtlsdr_open()
282  * \param on 0 means disabled, 1 I-ADC input enabled, 2 Q-ADC input enabled
283  * \return 0 on success
284  */
285 RTLSDR_API int rtlsdr_set_direct_sampling(rtlsdr_dev_t *dev, int on);
286
287 /*!
288  * Get state of the direct sampling mode
289  *
290  * \param dev the device handle given by rtlsdr_open()
291  * \return -1 on error, 0 means disabled, 1 I-ADC input enabled
292  *          2 Q-ADC input enabled
293  */
294 RTLSDR_API int rtlsdr_get_direct_sampling(rtlsdr_dev_t *dev);
295
296 /*!
297  * Enable or disable offset tuning for zero-IF tuners, which allows to avoid
298  * problems caused by the DC offset of the ADCs and 1/f noise.
299  *
300  * \param dev the device handle given by rtlsdr_open()
301  * \param on 0 means disabled, 1 enabled
302  * \return 0 on success
303  */
304 RTLSDR_API int rtlsdr_set_offset_tuning(rtlsdr_dev_t *dev, int on);
305
306 /*!
307  * Get state of the offset tuning mode
308  *
309  * \param dev the device handle given by rtlsdr_open()
310  * \return -1 on error, 0 means disabled, 1 enabled
311  */
312 RTLSDR_API int rtlsdr_get_offset_tuning(rtlsdr_dev_t *dev);
313
314 /* streaming functions */
315
316 RTLSDR_API int rtlsdr_reset_buffer(rtlsdr_dev_t *dev);
317
318 RTLSDR_API int rtlsdr_read_sync(rtlsdr_dev_t *dev, void *buf, int len, int *n_read);
319
320 typedef void(*rtlsdr_read_async_cb_t)(unsigned char *buf, uint32_t len, void *ctx);
321
322 /*!
323  * Read samples from the device asynchronously. This function will block until
324  * it is being canceled using rtlsdr_cancel_async()
325  *
326  * NOTE: This function is deprecated and is subject for removal.
327  *
328  * \param dev the device handle given by rtlsdr_open()
329  * \param cb callback function to return received samples
330  * \param ctx user specific context to pass via the callback function
331  * \return 0 on success
332  */
333 RTLSDR_API int rtlsdr_wait_async(rtlsdr_dev_t *dev, rtlsdr_read_async_cb_t cb, void *ctx);
334
335 /*!
336  * Read samples from the device asynchronously. This function will block until
337  * it is being canceled using rtlsdr_cancel_async()
338  *
339  * \param dev the device handle given by rtlsdr_open()
340  * \param cb callback function to return received samples
341  * \param ctx user specific context to pass via the callback function
342  * \param buf_num optional buffer count, buf_num * buf_len = overall buffer size
343  *                set to 0 for default buffer count (32)
344  * \param buf_len optional buffer length, must be multiple of 512,
345  *                set to 0 for default buffer length (16 * 32 * 512)
346  * \return 0 on success
347  */
348 RTLSDR_API int rtlsdr_read_async(rtlsdr_dev_t *dev,
349                                  rtlsdr_read_async_cb_t cb,
350                                  void *ctx,
351                                  uint32_t buf_num,
352                                  uint32_t buf_len);
353
354 /*!
355  * Cancel all pending asynchronous operations on the device.
356  *
357  * \param dev the device handle given by rtlsdr_open()
358  * \return 0 on success
359  */
360 RTLSDR_API int rtlsdr_cancel_async(rtlsdr_dev_t *dev);
361
362 #ifdef __cplusplus
363 }
364 #endif
365
366 #endif /* __RTL_SDR_H */