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