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