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 */