GNU Radio's OsmoSDR Package
osmosdr_src_iface.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 
21 #ifndef OSMOSDR_SRC_IFACE_H
22 #define OSMOSDR_SRC_IFACE_H
23 
24 #include <osmosdr/osmosdr_ranges.h>
25 #include <gr_basic_block.h>
26 
27 class osmosdr_src_iface;
28 
29 typedef boost::shared_ptr<osmosdr_src_iface> osmosdr_src_iface_sptr;
30 
31 /*!
32  * TODO: document
33  *
34  */
36 {
37 public:
38  /*!
39  * Get the number of channels the underlying radio hardware offers.
40  * \return the number of available channels
41  */
42  virtual size_t get_num_channels( void ) = 0;
43 
44  /*!
45  * Get the possible sample rates for the underlying radio hardware.
46  * \return a range of rates in Sps
47  */
48  virtual osmosdr::meta_range_t get_sample_rates( void ) = 0;
49 
50  /*!
51  * Set the sample rate for the underlying radio hardware.
52  * This also will select the appropriate IF bandpass, if applicable.
53  * \param rate a new rate in Sps
54  */
55  virtual double set_sample_rate( double rate ) = 0;
56 
57  /*!
58  * Get the sample rate for the underlying radio hardware.
59  * This is the actual sample rate and may differ from the rate set.
60  * \return the actual rate in Sps
61  */
62  virtual double get_sample_rate( void ) = 0;
63 
64  /*!
65  * Get the tunable frequency range for the underlying radio hardware.
66  * \param chan the channel index 0 to N-1
67  * \return the frequency range in Hz
68  */
69  virtual osmosdr::freq_range_t get_freq_range( size_t chan = 0 ) = 0;
70 
71  /*!
72  * Tune the underlying radio hardware to the desired center frequency.
73  * This also will select the appropriate RF bandpass.
74  * \param freq the desired frequency in Hz
75  * \param chan the channel index 0 to N-1
76  * \return the actual frequency in Hz
77  */
78  virtual double set_center_freq( double freq, size_t chan = 0 ) = 0;
79 
80  /*!
81  * Get the center frequency the underlying radio hardware is tuned to.
82  * This is the actual frequency and may differ from the frequency set.
83  * \param chan the channel index 0 to N-1
84  * \return the frequency in Hz
85  */
86  virtual double get_center_freq( size_t chan = 0 ) = 0;
87 
88  /*!
89  * Set the frequency correction value in parts per million.
90  * \param ppm the desired correction value in parts per million
91  * \param chan the channel index 0 to N-1
92  * \return correction value in parts per million
93  */
94  virtual double set_freq_corr( double ppm, size_t chan = 0 ) = 0;
95 
96  /*!
97  * Get the frequency correction value.
98  * \param chan the channel index 0 to N-1
99  * \return correction value in parts per million
100  */
101  virtual double get_freq_corr( size_t chan = 0 ) = 0;
102 
103  /*!
104  * Get the gain stage names of the underlying radio hardware.
105  * \param chan the channel index 0 to N-1
106  * \return a vector of strings containing the names of gain stages
107  */
108  virtual std::vector<std::string> get_gain_names( size_t chan = 0 ) = 0;
109 
110  /*!
111  * Get the settable overall gain range for the underlying radio hardware.
112  * \param chan the channel index 0 to N-1
113  * \return the gain range in dB
114  */
115  virtual osmosdr::gain_range_t get_gain_range( size_t chan = 0 ) = 0;
116 
117  /*!
118  * Get the settable gain range for a specific gain stage.
119  * \param name the name of the gain stage
120  * \param chan the channel index 0 to N-1
121  * \return the gain range in dB
122  */
123  virtual osmosdr::gain_range_t get_gain_range( const std::string & name,
124  size_t chan = 0 ) = 0;
125 
126  /*!
127  * Set the gain mode for the underlying radio hardware.
128  * This might be supported only for certain hardware types.
129  * \param automatic the gain mode (true means automatic gain mode)
130  * \param chan the channel index 0 to N-1
131  * \return the actual gain mode
132  */
133  virtual bool set_gain_mode( bool automatic, size_t chan = 0 ) { return false; }
134 
135  /*!
136  * Get the gain mode selected for the underlying radio hardware.
137  * \param chan the channel index 0 to N-1
138  * \return the actual gain mode (true means automatic gain mode)
139  */
140  virtual bool get_gain_mode( size_t chan = 0 ) { return false; }
141 
142  /*!
143  * Set the gain for the underlying radio hardware.
144  * This function will automatically distribute the desired gain value over
145  * available gain stages in an appropriate way and return the actual value.
146  * \param gain the gain in dB
147  * \param chan the channel index 0 to N-1
148  * \return the actual gain in dB
149  */
150  virtual double set_gain( double gain, size_t chan = 0 ) = 0;
151 
152  /*!
153  * Set the named gain on the underlying radio hardware.
154  * \param gain the gain in dB
155  * \param name the name of the gain stage
156  * \param chan the channel index 0 to N-1
157  * \return the actual gain in dB
158  */
159  virtual double set_gain( double gain,
160  const std::string & name,
161  size_t chan = 0 ) = 0;
162 
163  /*!
164  * Get the actual gain setting of the underlying radio hardware.
165  * \param chan the channel index 0 to N-1
166  * \return the actual gain in dB
167  */
168  virtual double get_gain( size_t chan = 0 ) = 0;
169 
170  /*!
171  * Get the actual gain setting of a named stage.
172  * \param name the name of the gain stage
173  * \param chan the channel index 0 to N-1
174  * \return the actual gain in dB
175  */
176  virtual double get_gain( const std::string & name, size_t chan = 0 ) = 0;
177 
178  /*!
179  * Set the IF gain for the underlying radio hardware.
180  * This function will automatically distribute the desired gain value over
181  * available IF gain stages in an appropriate way and return the actual value.
182  * \param gain the gain in dB
183  * \param chan the channel index 0 to N-1
184  * \return the actual gain in dB
185  */
186  virtual double set_if_gain( double gain, size_t chan = 0 ) { return 0; }
187 
188  /*!
189  * Get the available antennas of the underlying radio hardware.
190  * \param chan the channel index 0 to N-1
191  * \return a vector of strings containing the names of available antennas
192  */
193  virtual std::vector< std::string > get_antennas( size_t chan = 0 ) = 0;
194 
195  /*!
196  * Select the active antenna of the underlying radio hardware.
197  * \param chan the channel index 0 to N-1
198  * \return the actual antenna's name
199  */
200  virtual std::string set_antenna( const std::string & antenna,
201  size_t chan = 0 ) = 0;
202 
203  /*!
204  * Get the actual underlying radio hardware antenna setting.
205  * \param chan the channel index 0 to N-1
206  * \return antenna the actual antenna's name
207  */
208  virtual std::string get_antenna( size_t chan = 0 ) = 0;
209 };
210 
211 #endif // OSMOSDR_SRC_IFACE_H