GNU Radio's TEST Package
source_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_SOURCE_IFACE_H
22#define OSMOSDR_SOURCE_IFACE_H
23
24#include <osmosdr/ranges.h>
25#include <osmosdr/time_spec.h>
26#include <gnuradio/basic_block.h>
27
28/*!
29 * TODO: document
30 *
31 */
33{
34public:
35 /*!
36 * Get the number of channels the underlying radio hardware offers.
37 * \return the number of available channels
38 */
39 virtual size_t get_num_channels( void ) = 0;
40
41 /*!
42 * \brief seek file to \p seek_point relative to \p whence
43 *
44 * \param seek_point sample offset in file
45 * \param whence one of SEEK_SET, SEEK_CUR, SEEK_END (man fseek)
46 * \param chan the channel index 0 to N-1
47 * \return true on success
48 */
49 virtual bool seek( long seek_point, int whence, size_t chan = 0 ) { return false; }
50
51 /*!
52 * Get the possible sample rates for the underlying radio hardware.
53 * \return a range of rates in Sps
54 */
56
57 /*!
58 * Set the sample rate for the underlying radio hardware.
59 * This also will select the appropriate IF bandpass, if applicable.
60 * \param rate a new rate in Sps
61 */
62 virtual double set_sample_rate( double rate ) = 0;
63
64 /*!
65 * Get the sample rate for the underlying radio hardware.
66 * This is the actual sample rate and may differ from the rate set.
67 * \return the actual rate in Sps
68 */
69 virtual double get_sample_rate( void ) = 0;
70
71 /*!
72 * Get the tunable frequency range for the underlying radio hardware.
73 * \param chan the channel index 0 to N-1
74 * \return the frequency range in Hz
75 */
76 virtual osmosdr::freq_range_t get_freq_range( size_t chan = 0 ) = 0;
77
78 /*!
79 * Tune the underlying radio hardware to the desired center frequency.
80 * This also will select the appropriate RF bandpass.
81 * \param freq the desired frequency in Hz
82 * \param chan the channel index 0 to N-1
83 * \return the actual frequency in Hz
84 */
85 virtual double set_center_freq( double freq, size_t chan = 0 ) = 0;
86
87 /*!
88 * Get the center frequency the underlying radio hardware is tuned to.
89 * This is the actual frequency and may differ from the frequency set.
90 * \param chan the channel index 0 to N-1
91 * \return the frequency in Hz
92 */
93 virtual double get_center_freq( size_t chan = 0 ) = 0;
94
95 /*!
96 * Set the frequency correction value in parts per million.
97 * \param ppm the desired correction value in parts per million
98 * \param chan the channel index 0 to N-1
99 * \return correction value in parts per million
100 */
101 virtual double set_freq_corr( double ppm, size_t chan = 0 ) = 0;
102
103 /*!
104 * Get the frequency correction value.
105 * \param chan the channel index 0 to N-1
106 * \return correction value in parts per million
107 */
108 virtual double get_freq_corr( size_t chan = 0 ) = 0;
109
110 /*!
111 * Get the gain stage names of the underlying radio hardware.
112 * \param chan the channel index 0 to N-1
113 * \return a vector of strings containing the names of gain stages
114 */
115 virtual std::vector<std::string> get_gain_names( size_t chan = 0 ) = 0;
116
117 /*!
118 * Get the settable overall gain range for the underlying radio hardware.
119 * \param chan the channel index 0 to N-1
120 * \return the gain range in dB
121 */
122 virtual osmosdr::gain_range_t get_gain_range( size_t chan = 0 ) = 0;
123
124 /*!
125 * Get the settable gain range for a specific gain stage.
126 * \param name the name of the gain stage
127 * \param chan the channel index 0 to N-1
128 * \return the gain range in dB
129 */
130 virtual osmosdr::gain_range_t get_gain_range( const std::string & name,
131 size_t chan = 0 ) = 0;
132
133 /*!
134 * Set the gain mode for the underlying radio hardware.
135 * This might be supported only for certain hardware types.
136 * \param automatic the gain mode (true means automatic gain mode)
137 * \param chan the channel index 0 to N-1
138 * \return the actual gain mode
139 */
140 virtual bool set_gain_mode( bool automatic, size_t chan = 0 ) { return false; }
141
142 /*!
143 * Get the gain mode selected for the underlying radio hardware.
144 * \param chan the channel index 0 to N-1
145 * \return the actual gain mode (true means automatic gain mode)
146 */
147 virtual bool get_gain_mode( size_t chan = 0 ) { return false; }
148
149 /*!
150 * Set the gain for the underlying radio hardware.
151 * This function will automatically distribute the desired gain value over
152 * available gain stages in an appropriate way and return the actual value.
153 * \param gain the gain in dB
154 * \param chan the channel index 0 to N-1
155 * \return the actual gain in dB
156 */
157 virtual double set_gain( double gain, size_t chan = 0 ) = 0;
158
159 /*!
160 * Set the named gain on the underlying radio hardware.
161 * \param gain the gain in dB
162 * \param name the name of the gain stage
163 * \param chan the channel index 0 to N-1
164 * \return the actual gain in dB
165 */
166 virtual double set_gain( double gain,
167 const std::string & name,
168 size_t chan = 0 ) = 0;
169
170 /*!
171 * Get the actual gain setting of the underlying radio hardware.
172 * \param chan the channel index 0 to N-1
173 * \return the actual gain in dB
174 */
175 virtual double get_gain( size_t chan = 0 ) = 0;
176
177 /*!
178 * Get the actual gain setting of a named stage.
179 * \param name the name of the gain stage
180 * \param chan the channel index 0 to N-1
181 * \return the actual gain in dB
182 */
183 virtual double get_gain( const std::string & name, size_t chan = 0 ) = 0;
184
185 /*!
186 * Set the IF gain for the underlying radio hardware.
187 * This function will automatically distribute the desired gain value over
188 * available IF gain stages in an appropriate way and return the actual value.
189 * \param gain the gain in dB
190 * \param chan the channel index 0 to N-1
191 * \return the actual gain in dB
192 */
193 virtual double set_if_gain( double gain, size_t chan = 0 ) { return 0; }
194
195 /*!
196 * Set the BB gain for the underlying radio hardware.
197 * This function will automatically distribute the desired gain value over
198 * available BB gain stages in an appropriate way and return the actual value.
199 * \param gain the gain in dB
200 * \param chan the channel index 0 to N-1
201 * \return the actual gain in dB
202 */
203 virtual double set_bb_gain( double gain, size_t chan = 0 ) { return 0; }
204
205 /*!
206 * Get the available antennas of the underlying radio hardware.
207 * \param chan the channel index 0 to N-1
208 * \return a vector of strings containing the names of available antennas
209 */
210 virtual std::vector< std::string > get_antennas( size_t chan = 0 ) = 0;
211
212 /*!
213 * Select the active antenna of the underlying radio hardware.
214 * \param antenna the antenna name
215 * \param chan the channel index 0 to N-1
216 * \return the actual antenna's name
217 */
218 virtual std::string set_antenna( const std::string & antenna,
219 size_t chan = 0 ) = 0;
220
221 /*!
222 * Get the actual underlying radio hardware antenna setting.
223 * \param chan the channel index 0 to N-1
224 * \return the actual antenna's name
225 */
226 virtual std::string get_antenna( size_t chan = 0 ) = 0;
227
228 /*!
229 * Set the RX frontend DC correction mode.
230 * The automatic correction subtracts out the long-run average.
231 *
232 * When disabled, the averaging option operation is reset.
233 * Once in Manual mode, the average value will be held constant until
234 * the user re-enables the automatic correction or overrides the
235 * value by manually setting the offset.
236 *
237 * \param mode dc offset correction mode: 0 = Off, 1 = Manual, 2 = Automatic
238 * \param chan the channel index 0 to N-1
239 */
240 virtual void set_dc_offset_mode( int mode, size_t chan = 0 ) { }
241
242 /*!
243 * Set a constant DC offset value.
244 * The value is complex to control both I and Q.
245 * Only set this when automatic correction is disabled.
246 *
247 * \param offset the dc offset (1.0 is full-scale)
248 * \param chan the channel index 0 to N-1
249 */
250 virtual void set_dc_offset( const std::complex<double> &offset, size_t chan = 0 ) { }
251
252 /*!
253 * Set the RX frontend IQ balance mode.
254 *
255 * \param mode iq balance correction mode: 0 = Off, 1 = Manual, 2 = Automatic
256 * \param chan the channel index 0 to N-1
257 */
258 virtual void set_iq_balance_mode( int mode, size_t chan = 0 ) { }
259
260 /*!
261 * Set the RX frontend IQ balance correction.
262 * Use this to adjust the magnitude and phase of I and Q.
263 *
264 * \param balance the complex correction value
265 * \param chan the channel index 0 to N-1
266 */
267 virtual void set_iq_balance( const std::complex<double> &balance, size_t chan = 0 ) { }
268
269 /*!
270 * Set the bandpass filter on the radio frontend.
271 * \param bandwidth the filter bandwidth in Hz, set to 0 for automatic selection
272 * \param chan the channel index 0 to N-1
273 * \return the actual filter bandwidth in Hz
274 */
275 virtual double set_bandwidth( double bandwidth, size_t chan = 0 ) { return 0; }
276
277 /*!
278 * Get the actual bandpass filter setting on the radio frontend.
279 * \param chan the channel index 0 to N-1
280 * \return the actual filter bandwidth in Hz
281 */
282 virtual double get_bandwidth( size_t chan = 0 ) { return 0; }
283
284 /*!
285 * Get the possible bandpass filter settings on the radio frontend.
286 * \param chan the channel index 0 to N-1
287 * \return a range of bandwidths in Hz
288 */
290 { return osmosdr::freq_range_t(); }
291
292 /*!
293 * Set the time source for the device.
294 * This sets the method of time synchronization,
295 * typically a pulse per second or an encoded time.
296 * Typical options for source: external, MIMO.
297 * \param source a string representing the time source
298 * \param mboard which motherboard to set the config
299 */
300 virtual void set_time_source(const std::string &source,
301 const size_t mboard = 0) { }
302
303 /*!
304 * Get the currently set time source.
305 * \param mboard which motherboard to get the config
306 * \return the string representing the time source
307 */
308 virtual std::string get_time_source(const size_t mboard) { return ""; }
309
310 /*!
311 * Get a list of possible time sources.
312 * \param mboard which motherboard to get the list
313 * \return a vector of strings for possible settings
314 */
315 virtual std::vector<std::string> get_time_sources(const size_t mboard)
316 {
317 return std::vector<std::string>();
318 }
319
320 /*!
321 * Set the clock source for the device.
322 * This sets the source for a 10 Mhz reference clock.
323 * Typical options for source: internal, external, MIMO.
324 * \param source a string representing the clock source
325 * \param mboard which motherboard to set the config
326 */
327 virtual void set_clock_source(const std::string &source,
328 const size_t mboard = 0) { }
329
330 /*!
331 * Get the currently set clock source.
332 * \param mboard which motherboard to get the config
333 * \return the string representing the clock source
334 */
335 virtual std::string get_clock_source(const size_t mboard) { return ""; }
336
337 /*!
338 * Get a list of possible clock sources.
339 * \param mboard which motherboard to get the list
340 * \return a vector of strings for possible settings
341 */
342 virtual std::vector<std::string> get_clock_sources(const size_t mboard)
343 {
344 return std::vector<std::string>();
345 }
346
347 /*!
348 * Get the master clock rate.
349 * \param mboard the motherboard index 0 to M-1
350 * \return the clock rate in Hz
351 */
352 virtual double get_clock_rate(size_t mboard = 0) { return 0; }
353
354 /*!
355 * Set the master clock rate.
356 * \param rate the new rate in Hz
357 * \param mboard the motherboard index 0 to M-1
358 */
359 virtual void set_clock_rate(double rate, size_t mboard = 0) { }
360
361 /*!
362 * Get the current time registers.
363 * \param mboard the motherboard index 0 to M-1
364 * \return the current device time
365 */
366 virtual ::osmosdr::time_spec_t get_time_now(size_t mboard = 0)
367 {
368 return ::osmosdr::time_spec_t::get_system_time();
369 }
370
371 /*!
372 * Get the time when the last pps pulse occured.
373 * \param mboard the motherboard index 0 to M-1
374 * \return the current device time
375 */
376 virtual ::osmosdr::time_spec_t get_time_last_pps(size_t mboard = 0)
377 {
378 return ::osmosdr::time_spec_t::get_system_time();
379 }
380
381 /*!
382 * Sets the time registers immediately.
383 * \param time_spec the new time
384 * \param mboard the motherboard index 0 to M-1
385 */
386 virtual void set_time_now(const ::osmosdr::time_spec_t &time_spec,
387 size_t mboard = 0) { }
388
389 /*!
390 * Set the time registers at the next pps.
391 * \param time_spec the new time
392 */
393 virtual void set_time_next_pps(const ::osmosdr::time_spec_t &time_spec) { }
394
395 /*!
396 * Sync the time registers with an unknown pps edge.
397 * \param time_spec the new time
398 */
399 virtual void set_time_unknown_pps(const ::osmosdr::time_spec_t &time_spec) { }
400};
401
402#endif // OSMOSDR_SOURCE_IFACE_H
Definition: source_iface.h:33
virtual double get_freq_corr(size_t chan=0)=0
virtual double set_sample_rate(double rate)=0
virtual double get_bandwidth(size_t chan=0)
Definition: source_iface.h:282
virtual double get_gain(size_t chan=0)=0
virtual void set_dc_offset(const std::complex< double > &offset, size_t chan=0)
Definition: source_iface.h:250
virtual double set_bandwidth(double bandwidth, size_t chan=0)
Definition: source_iface.h:275
virtual ::osmosdr::time_spec_t get_time_last_pps(size_t mboard=0)
Definition: source_iface.h:376
virtual osmosdr::freq_range_t get_bandwidth_range(size_t chan=0)
Definition: source_iface.h:289
virtual void set_iq_balance_mode(int mode, size_t chan=0)
Definition: source_iface.h:258
virtual void set_clock_source(const std::string &source, const size_t mboard=0)
Definition: source_iface.h:327
virtual osmosdr::freq_range_t get_freq_range(size_t chan=0)=0
virtual void set_time_now(const ::osmosdr::time_spec_t &time_spec, size_t mboard=0)
Definition: source_iface.h:386
virtual void set_iq_balance(const std::complex< double > &balance, size_t chan=0)
Definition: source_iface.h:267
virtual osmosdr::meta_range_t get_sample_rates(void)=0
virtual std::vector< std::string > get_antennas(size_t chan=0)=0
virtual double set_freq_corr(double ppm, size_t chan=0)=0
virtual double get_sample_rate(void)=0
virtual bool seek(long seek_point, int whence, size_t chan=0)
seek file to seek_point relative to whence
Definition: source_iface.h:49
virtual std::vector< std::string > get_clock_sources(const size_t mboard)
Definition: source_iface.h:342
virtual void set_dc_offset_mode(int mode, size_t chan=0)
Definition: source_iface.h:240
virtual std::vector< std::string > get_time_sources(const size_t mboard)
Definition: source_iface.h:315
virtual double set_gain(double gain, size_t chan=0)=0
virtual ::osmosdr::time_spec_t get_time_now(size_t mboard=0)
Definition: source_iface.h:366
virtual size_t get_num_channels(void)=0
virtual std::string set_antenna(const std::string &antenna, size_t chan=0)=0
virtual std::string get_time_source(const size_t mboard)
Definition: source_iface.h:308
virtual void set_time_next_pps(const ::osmosdr::time_spec_t &time_spec)
Definition: source_iface.h:393
virtual double set_bb_gain(double gain, size_t chan=0)
Definition: source_iface.h:203
virtual double get_center_freq(size_t chan=0)=0
virtual bool set_gain_mode(bool automatic, size_t chan=0)
Definition: source_iface.h:140
virtual std::string get_antenna(size_t chan=0)=0
virtual double get_gain(const std::string &name, size_t chan=0)=0
virtual std::vector< std::string > get_gain_names(size_t chan=0)=0
virtual std::string get_clock_source(const size_t mboard)
Definition: source_iface.h:335
virtual double set_center_freq(double freq, size_t chan=0)=0
virtual osmosdr::gain_range_t get_gain_range(const std::string &name, size_t chan=0)=0
virtual void set_time_unknown_pps(const ::osmosdr::time_spec_t &time_spec)
Definition: source_iface.h:399
virtual double set_if_gain(double gain, size_t chan=0)
Definition: source_iface.h:193
virtual osmosdr::gain_range_t get_gain_range(size_t chan=0)=0
virtual double get_clock_rate(size_t mboard=0)
Definition: source_iface.h:352
virtual void set_time_source(const std::string &source, const size_t mboard=0)
Definition: source_iface.h:300
virtual void set_clock_rate(double rate, size_t mboard=0)
Definition: source_iface.h:359
virtual double set_gain(double gain, const std::string &name, size_t chan=0)=0
virtual bool get_gain_mode(size_t chan=0)
Definition: source_iface.h:147
meta_range_t freq_range_t
Definition: ranges.h:125
Definition: ranges.h:75