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