GNU Radio's OsmoSDR Package
source.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2012 Dimitri Stolnikov <horiz0n@gmx.net>
4  *
5  * GNU Radio is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 3, or (at your option)
8  * any later version.
9  *
10  * GNU Radio is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with GNU Radio; see the file COPYING. If not, write to
17  * the Free Software Foundation, Inc., 51 Franklin Street,
18  * Boston, MA 02110-1301, USA.
19  */
20 #ifndef INCLUDED_OSMOSDR_SOURCE_H
21 #define INCLUDED_OSMOSDR_SOURCE_H
22 
23 #include <osmosdr/api.h>
24 #include <osmosdr/ranges.h>
25 #include <gnuradio/hier_block2.h>
26 
27 namespace osmosdr {
28 
29 class source;
30 
31 /*!
32  * \brief Provides a stream of complex samples.
33  * \ingroup block
34  *
35  * This uses the preferred technique: subclassing gr::hier_block2.
36  */
37 class OSMOSDR_API source : virtual public gr::hier_block2
38 {
39 public:
40  typedef boost::shared_ptr< source > sptr;
41 
42  /*!
43  * \brief Return a shared_ptr to a new instance of source.
44  *
45  * To avoid accidental use of raw pointers, source's
46  * constructor is private. osmosdr::source::make is the public
47  * interface for creating new instances.
48  *
49  * \param args the address to identify the hardware
50  * \return a new osmosdr source block object
51  */
52  static sptr make( const std::string & args = "" );
53 
54  /*!
55  * Get the number of channels the underlying radio hardware offers.
56  * \return the number of available channels
57  */
58  virtual size_t get_num_channels( void ) = 0;
59 
60  /*!
61  * \brief seek file to \p seek_point relative to \p whence
62  *
63  * \param seek_point sample offset in file
64  * \param whence one of SEEK_SET, SEEK_CUR, SEEK_END (man fseek)
65  * \return true on success
66  */
67  virtual bool seek( long seek_point, int whence, size_t chan = 0 ) = 0;
68 
69  /*!
70  * Get the possible sample rates for the underlying radio hardware.
71  * \return a range of rates in Sps
72  */
73  virtual osmosdr::meta_range_t get_sample_rates( void ) = 0;
74 
75  /*!
76  * Set the sample rate for the underlying radio hardware.
77  * This also will select the appropriate IF bandpass, if applicable.
78  * \param rate a new rate in Sps
79  */
80  virtual double set_sample_rate( double rate ) = 0;
81 
82  /*!
83  * Get the sample rate for the underlying radio hardware.
84  * This is the actual sample rate and may differ from the rate set.
85  * \return the actual rate in Sps
86  */
87  virtual double get_sample_rate( void ) = 0;
88 
89  /*!
90  * Get the tunable frequency range for the underlying radio hardware.
91  * \param chan the channel index 0 to N-1
92  * \return the frequency range in Hz
93  */
94  virtual osmosdr::freq_range_t get_freq_range( size_t chan = 0 ) = 0;
95 
96  /*!
97  * Tune the underlying radio hardware to the desired center frequency.
98  * This also will select the appropriate RF bandpass.
99  * \param freq the desired frequency in Hz
100  * \param chan the channel index 0 to N-1
101  * \return the actual frequency in Hz
102  */
103  virtual double set_center_freq( double freq, size_t chan = 0 ) = 0;
104 
105  /*!
106  * Get the center frequency the underlying radio hardware is tuned to.
107  * This is the actual frequency and may differ from the frequency set.
108  * \param chan the channel index 0 to N-1
109  * \return the frequency in Hz
110  */
111  virtual double get_center_freq( size_t chan = 0 ) = 0;
112 
113  /*!
114  * Set the frequency correction value in parts per million.
115  * \param ppm the desired correction value in parts per million
116  * \param chan the channel index 0 to N-1
117  * \return correction value in parts per million
118  */
119  virtual double set_freq_corr( double ppm, size_t chan = 0 ) = 0;
120 
121  /*!
122  * Get the frequency correction value.
123  * \param chan the channel index 0 to N-1
124  * \return correction value in parts per million
125  */
126  virtual double get_freq_corr( size_t chan = 0 ) = 0;
127 
128  /*!
129  * Get the gain stage names of the underlying radio hardware.
130  * \param chan the channel index 0 to N-1
131  * \return a vector of strings containing the names of gain stages
132  */
133  virtual std::vector<std::string> get_gain_names( size_t chan = 0 ) = 0;
134 
135  /*!
136  * Get the settable overall gain range for the underlying radio hardware.
137  * \param chan the channel index 0 to N-1
138  * \return the gain range in dB
139  */
140  virtual osmosdr::gain_range_t get_gain_range( size_t chan = 0 ) = 0;
141 
142  /*!
143  * Get the settable gain range for a specific gain stage.
144  * \param name the name of the gain stage
145  * \param chan the channel index 0 to N-1
146  * \return the gain range in dB
147  */
148  virtual osmosdr::gain_range_t get_gain_range( const std::string & name,
149  size_t chan = 0 ) = 0;
150 
151  /*!
152  * Set the gain mode for the underlying radio hardware.
153  * This might be supported only for certain hardware types.
154  * \param automatic the gain mode (true means automatic gain mode)
155  * \param chan the channel index 0 to N-1
156  * \return the actual gain mode
157  */
158  virtual bool set_gain_mode( bool automatic, size_t chan = 0 ) = 0;
159 
160  /*!
161  * Get the gain mode selected for the underlying radio hardware.
162  * \param chan the channel index 0 to N-1
163  * \return the actual gain mode (true means automatic gain mode)
164  */
165  virtual bool get_gain_mode( size_t chan = 0 ) = 0;
166 
167  /*!
168  * Set the gain for the underlying radio hardware.
169  * This function will automatically distribute the desired gain value over
170  * available gain stages in an appropriate way and return the actual value.
171  * \param gain the gain in dB
172  * \param chan the channel index 0 to N-1
173  * \return the actual gain in dB
174  */
175  virtual double set_gain( double gain, size_t chan = 0 ) = 0;
176 
177  /*!
178  * Set the named gain on the underlying radio hardware.
179  * \param gain the gain in dB
180  * \param name the name of the gain stage
181  * \param chan the channel index 0 to N-1
182  * \return the actual gain in dB
183  */
184  virtual double set_gain( double gain,
185  const std::string & name,
186  size_t chan = 0 ) = 0;
187 
188  /*!
189  * Get the actual gain setting of the underlying radio hardware.
190  * \param chan the channel index 0 to N-1
191  * \return the actual gain in dB
192  */
193  virtual double get_gain( size_t chan = 0 ) = 0;
194 
195  /*!
196  * Get the actual gain setting of a named stage.
197  * \param name the name of the gain stage
198  * \param chan the channel index 0 to N-1
199  * \return the actual gain in dB
200  */
201  virtual double get_gain( const std::string & name, size_t chan = 0 ) = 0;
202 
203  /*!
204  * Set the IF gain for the underlying radio hardware.
205  * This function will automatically distribute the desired gain value over
206  * available IF gain stages in an appropriate way and return the actual value.
207  * \param gain the gain in dB
208  * \param chan the channel index 0 to N-1
209  * \return the actual gain in dB
210  */
211  virtual double set_if_gain( double gain, size_t chan = 0 ) = 0;
212 
213  /*!
214  * Set the BB gain for the underlying radio hardware.
215  * This function will automatically distribute the desired gain value over
216  * available BB gain stages in an appropriate way and return the actual value.
217  * \param gain the gain in dB
218  * \param chan the channel index 0 to N-1
219  * \return the actual gain in dB
220  */
221  virtual double set_bb_gain( double gain, size_t chan = 0 ) = 0;
222 
223  /*!
224  * Get the available antennas of the underlying radio hardware.
225  * \param chan the channel index 0 to N-1
226  * \return a vector of strings containing the names of available antennas
227  */
228  virtual std::vector< std::string > get_antennas( size_t chan = 0 ) = 0;
229 
230  /*!
231  * Select the active antenna of the underlying radio hardware.
232  * \param antenna name of the antenna to be selected
233  * \param chan the channel index 0 to N-1
234  * \return the actual antenna's name
235  */
236  virtual std::string set_antenna( const std::string & antenna,
237  size_t chan = 0 ) = 0;
238 
239  /*!
240  * Get the actual underlying radio hardware antenna setting.
241  * \param chan the channel index 0 to N-1
242  * \return the actual antenna's name
243  */
244  virtual std::string get_antenna( size_t chan = 0 ) = 0;
245 
247  DCOffsetOff = 0,
249  DCOffsetAutomatic
250  };
251 
252  /*!
253  * Set the RX frontend DC correction mode.
254  * The automatic correction subtracts out the long-run average.
255  *
256  * When disabled, the averaging option operation is reset.
257  * Once in Manual mode, the average value will be held constant until
258  * the user re-enables the automatic correction or overrides the
259  * value by manually setting the offset.
260  *
261  * \param mode dc offset correction mode: 0 = Off, 1 = Manual, 2 = Automatic
262  * \param chan the channel index 0 to N-1
263  */
264  virtual void set_dc_offset_mode( int mode, size_t chan = 0) = 0;
265 
266  /*!
267  * Set the RX frontend DC offset value.
268  * The value is complex to control both I and Q.
269  * Only set this when automatic correction is disabled.
270  *
271  * \param offset the dc offset (1.0 is full-scale)
272  * \param chan the channel index 0 to N-1
273  */
274  virtual void set_dc_offset( const std::complex<double> &offset, size_t chan = 0 ) = 0;
275 
277  IQBalanceOff = 0,
279  IQBalanceAutomatic
280  };
281 
282  /*!
283  * Set the RX frontend IQ balance mode.
284  *
285  * \param mode iq balance correction mode: 0 = Off, 1 = Manual, 2 = Automatic
286  * \param chan the channel index 0 to N-1
287  */
288  virtual void set_iq_balance_mode( int mode, size_t chan = 0 ) = 0;
289 
290  /*!
291  * Set the RX frontend IQ balance correction.
292  * Use this to adjust the magnitude and phase of I and Q.
293  *
294  * \param balance the complex correction value
295  * \param chan the channel index 0 to N-1
296  */
297  virtual void set_iq_balance( const std::complex<double> &balance, size_t chan = 0 ) = 0;
298 
299  /*!
300  * Set the bandpass filter on the radio frontend.
301  * \param bandwidth the filter bandwidth in Hz, set to 0 for automatic selection
302  * \param chan the channel index 0 to N-1
303  * \return the actual filter bandwidth in Hz
304  */
305  virtual double set_bandwidth( double bandwidth, size_t chan = 0 ) = 0;
306 
307  /*!
308  * Get the actual bandpass filter setting on the radio frontend.
309  * \param chan the channel index 0 to N-1
310  * \return the actual filter bandwidth in Hz
311  */
312  virtual double get_bandwidth( size_t chan = 0 ) = 0;
313 
314  /*!
315  * Get the possible bandpass filter settings on the radio frontend.
316  * \param chan the channel index 0 to N-1
317  * \return a range of bandwidths in Hz
318  */
319  virtual osmosdr::freq_range_t get_bandwidth_range( size_t chan = 0 ) = 0;
320 };
321 
322 } /* namespace osmosdr */
323 
324 #endif /* INCLUDED_OSMOSDR_SOURCE_H */
Definition: source.h:248
Definition: ranges.h:69
Provides a stream of complex samples.This uses the preferred technique: subclassing gr::hier_block2...
Definition: source.h:37
IQBalanceMode
Definition: source.h:276
boost::shared_ptr< source > sptr
Definition: source.h:40
Definition: source.h:278
#define OSMOSDR_API
Definition: api.h:30
DCOffsetMode
Definition: source.h:246
Definition: device.h:35