GNU Radio's OsmoSDR Package
sink_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_SINK_IFACE_H
22 #define OSMOSDR_SINK_IFACE_H
23 
24 #include <osmosdr/ranges.h>
25 #include <gnuradio/basic_block.h>
26 
27 /*!
28  * TODO: document
29  *
30  */
32 {
33 public:
34  /*!
35  * Get the number of channels the underlying radio hardware offers.
36  * \return the number of available channels
37  */
38  virtual size_t get_num_channels( void ) = 0;
39 
40  /*!
41  * Get the possible sample rates for the underlying radio hardware.
42  * \return a range of rates in Sps
43  */
44  virtual osmosdr::meta_range_t get_sample_rates( void ) = 0;
45 
46  /*!
47  * Set the sample rate for the underlying radio hardware.
48  * This also will select the appropriate IF bandpass, if applicable.
49  * \param rate a new rate in Sps
50  */
51  virtual double set_sample_rate( double rate ) = 0;
52 
53  /*!
54  * Get the sample rate for the underlying radio hardware.
55  * This is the actual sample rate and may differ from the rate set.
56  * \return the actual rate in Sps
57  */
58  virtual double get_sample_rate( void ) = 0;
59 
60  /*!
61  * Get the tunable frequency range for the underlying radio hardware.
62  * \param chan the channel index 0 to N-1
63  * \return the frequency range in Hz
64  */
65  virtual osmosdr::freq_range_t get_freq_range( size_t chan = 0 ) = 0;
66 
67  /*!
68  * Tune the underlying radio hardware to the desired center frequency.
69  * This also will select the appropriate RF bandpass.
70  * \param freq the desired frequency in Hz
71  * \param chan the channel index 0 to N-1
72  * \return the actual frequency in Hz
73  */
74  virtual double set_center_freq( double freq, size_t chan = 0 ) = 0;
75 
76  /*!
77  * Get the center frequency the underlying radio hardware is tuned to.
78  * This is the actual frequency and may differ from the frequency set.
79  * \param chan the channel index 0 to N-1
80  * \return the frequency in Hz
81  */
82  virtual double get_center_freq( size_t chan = 0 ) = 0;
83 
84  /*!
85  * Set the frequency correction value in parts per million.
86  * \param ppm the desired correction value in parts per million
87  * \param chan the channel index 0 to N-1
88  * \return correction value in parts per million
89  */
90  virtual double set_freq_corr( double ppm, size_t chan = 0 ) = 0;
91 
92  /*!
93  * Get the frequency correction value.
94  * \param chan the channel index 0 to N-1
95  * \return correction value in parts per million
96  */
97  virtual double get_freq_corr( size_t chan = 0 ) = 0;
98 
99  /*!
100  * Get the gain stage names of the underlying radio hardware.
101  * \param chan the channel index 0 to N-1
102  * \return a vector of strings containing the names of gain stages
103  */
104  virtual std::vector<std::string> get_gain_names( size_t chan = 0 ) = 0;
105 
106  /*!
107  * Get the settable overall gain range for the underlying radio hardware.
108  * \param chan the channel index 0 to N-1
109  * \return the gain range in dB
110  */
111  virtual osmosdr::gain_range_t get_gain_range( size_t chan = 0 ) = 0;
112 
113  /*!
114  * Get the settable gain range for a specific gain stage.
115  * \param name the name of the gain stage
116  * \param chan the channel index 0 to N-1
117  * \return the gain range in dB
118  */
119  virtual osmosdr::gain_range_t get_gain_range( const std::string & name,
120  size_t chan = 0 ) = 0;
121 
122  /*!
123  * Set the gain mode for the underlying radio hardware.
124  * This might be supported only for certain hardware types.
125  * \param automatic the gain mode (true means automatic gain mode)
126  * \param chan the channel index 0 to N-1
127  * \return the actual gain mode
128  */
129  virtual bool set_gain_mode( bool automatic, size_t chan = 0 ) { return false; }
130 
131  /*!
132  * Get the gain mode selected for the underlying radio hardware.
133  * \param chan the channel index 0 to N-1
134  * \return the actual gain mode (true means automatic gain mode)
135  */
136  virtual bool get_gain_mode( size_t chan = 0 ) { return false; }
137 
138  /*!
139  * Set the gain for the underlying radio hardware.
140  * This function will automatically distribute the desired gain value over
141  * available gain stages in an appropriate way and return the actual value.
142  * \param gain the gain in dB
143  * \param chan the channel index 0 to N-1
144  * \return the actual gain in dB
145  */
146  virtual double set_gain( double gain, size_t chan = 0 ) = 0;
147 
148  /*!
149  * Set the named gain on the underlying radio hardware.
150  * \param gain the gain in dB
151  * \param name the name of the gain stage
152  * \param chan the channel index 0 to N-1
153  * \return the actual gain in dB
154  */
155  virtual double set_gain( double gain,
156  const std::string & name,
157  size_t chan = 0 ) = 0;
158 
159  /*!
160  * Get the actual gain setting of the underlying radio hardware.
161  * \param chan the channel index 0 to N-1
162  * \return the actual gain in dB
163  */
164  virtual double get_gain( size_t chan = 0 ) = 0;
165 
166  /*!
167  * Get the actual gain setting of a named stage.
168  * \param name the name of the gain stage
169  * \param chan the channel index 0 to N-1
170  * \return the actual gain in dB
171  */
172  virtual double get_gain( const std::string & name, size_t chan = 0 ) = 0;
173 
174  /*!
175  * Set the IF gain for the underlying radio hardware.
176  * This function will automatically distribute the desired gain value over
177  * available IF gain stages in an appropriate way and return the actual value.
178  * \param gain the gain in dB
179  * \param chan the channel index 0 to N-1
180  * \return the actual gain in dB
181  */
182  virtual double set_if_gain( double gain, size_t chan = 0 ) { return 0; }
183 
184  /*!
185  * Set the BB gain for the underlying radio hardware.
186  * This function will automatically distribute the desired gain value over
187  * available BB gain stages in an appropriate way and return the actual value.
188  * \param gain the gain in dB
189  * \param chan the channel index 0 to N-1
190  * \return the actual gain in dB
191  */
192  virtual double set_bb_gain( double gain, size_t chan = 0 ) { return 0; }
193 
194  /*!
195  * Get the available antennas of the underlying radio hardware.
196  * \param chan the channel index 0 to N-1
197  * \return a vector of strings containing the names of available antennas
198  */
199  virtual std::vector< std::string > get_antennas( size_t chan = 0 ) = 0;
200 
201  /*!
202  * Select the active antenna of the underlying radio hardware.
203  * \param chan the channel index 0 to N-1
204  * \return the actual antenna's name
205  */
206  virtual std::string set_antenna( const std::string & antenna,
207  size_t chan = 0 ) = 0;
208 
209  /*!
210  * Get the actual underlying radio hardware antenna setting.
211  * \param chan the channel index 0 to N-1
212  * \return the actual antenna's name
213  */
214  virtual std::string get_antenna( size_t chan = 0 ) = 0;
215 
216  /*!
217  * Set the TX frontend DC offset value.
218  * The value is complex to control both I and Q.
219  *
220  * \param offset the dc offset (1.0 is full-scale)
221  * \param chan the channel index 0 to N-1
222  */
223  virtual void set_dc_offset( const std::complex<double> &offset, size_t chan = 0 ) { }
224 
225  /*!
226  * Set the TX frontend IQ balance correction.
227  * Use this to adjust the magnitude and phase of I and Q.
228  *
229  * \param balance the complex correction value
230  * \param chan the channel index 0 to N-1
231  */
232  virtual void set_iq_balance( const std::complex<double> &balance, size_t chan = 0 ) { }
233 
234  /*!
235  * Set the bandpass filter on the radio frontend.
236  * \param bandwidth the filter bandwidth in Hz, set to 0 for automatic selection
237  * \param chan the channel index 0 to N-1
238  * \return the actual filter bandwidth in Hz
239  */
240  virtual double set_bandwidth( double bandwidth, size_t chan = 0 ) { return 0; }
241 
242  /*!
243  * Get the actual bandpass filter setting on the radio frontend.
244  * \param chan the channel index 0 to N-1
245  * \return the actual filter bandwidth in Hz
246  */
247  virtual double get_bandwidth( size_t chan = 0 ) { return 0; }
248 
249  /*!
250  * Get the possible bandpass filter settings on the radio frontend.
251  * \param chan the channel index 0 to N-1
252  * \return a range of bandwidths in Hz
253  */
254  virtual osmosdr::freq_range_t get_bandwidth_range( size_t chan = 0 )
255  { return osmosdr::freq_range_t(); }
256 };
257 
258 #endif // OSMOSDR_SINK_IFACE_H
virtual double set_center_freq(double freq, size_t chan=0)=0
virtual double get_center_freq(size_t chan=0)=0
virtual osmosdr::gain_range_t get_gain_range(size_t chan=0)=0
meta_range_t freq_range_t
Definition: ranges.h:119
virtual osmosdr::freq_range_t get_bandwidth_range(size_t chan=0)
Definition: sink_iface.h:254
virtual std::vector< std::string > get_antennas(size_t chan=0)=0
virtual osmosdr::meta_range_t get_sample_rates(void)=0
virtual double set_freq_corr(double ppm, size_t chan=0)=0
virtual double get_gain(size_t chan=0)=0
virtual double set_if_gain(double gain, size_t chan=0)
Definition: sink_iface.h:182
Definition: ranges.h:69
virtual double set_gain(double gain, size_t chan=0)=0
Definition: sink_iface.h:31
virtual double set_bandwidth(double bandwidth, size_t chan=0)
Definition: sink_iface.h:240
virtual osmosdr::freq_range_t get_freq_range(size_t chan=0)=0
virtual bool set_gain_mode(bool automatic, size_t chan=0)
Definition: sink_iface.h:129
virtual std::string get_antenna(size_t chan=0)=0
virtual bool get_gain_mode(size_t chan=0)
Definition: sink_iface.h:136
virtual double get_sample_rate(void)=0
virtual void set_iq_balance(const std::complex< double > &balance, size_t chan=0)
Definition: sink_iface.h:232
virtual double get_bandwidth(size_t chan=0)
Definition: sink_iface.h:247
virtual size_t get_num_channels(void)=0
virtual double set_sample_rate(double rate)=0
virtual std::vector< std::string > get_gain_names(size_t chan=0)=0
virtual void set_dc_offset(const std::complex< double > &offset, size_t chan=0)
Definition: sink_iface.h:223
virtual std::string set_antenna(const std::string &antenna, size_t chan=0)=0
virtual double set_bb_gain(double gain, size_t chan=0)
Definition: sink_iface.h:192
virtual double get_freq_corr(size_t chan=0)=0