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