GNU Radio Manual and C++ API Reference  3.7.7
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
usrp_sink.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2010-2015 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * GNU Radio is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 3, or (at your option)
10  * any later version.
11  *
12  * GNU Radio is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with GNU Radio; see the file COPYING. If not, write to
19  * the Free Software Foundation, Inc., 51 Franklin Street,
20  * Boston, MA 02110-1301, USA.
21  */
22 
23 #ifndef INCLUDED_GR_UHD_USRP_SINK_H
24 #define INCLUDED_GR_UHD_USRP_SINK_H
25 
26 #include <gnuradio/uhd/api.h>
27 #include <gnuradio/sync_block.h>
28 #include <uhd/usrp/multi_usrp.hpp>
29 
30 // TODO In 3.8, UHD 3.4 will be required and we can remove all these ifdefs
31 #ifndef INCLUDED_UHD_STREAM_HPP
32 namespace uhd {
34  {
35  stream_args_t(const std::string &cpu = "",
36  const std::string &otw = "")
37  {
38  cpu_format = cpu;
39  otw_format = otw;
40  }
41  std::string cpu_format;
42  std::string otw_format;
43  device_addr_t args;
44  std::vector<size_t> channels;
45  };
46 }
47 # define INCLUDED_UHD_STREAM_HPP
48 #else
49 # define GR_UHD_USE_STREAM_API
50 #endif
51 
52 namespace gr {
53  namespace uhd {
54 
55  class uhd_usrp_sink;
56 
57  class GR_UHD_API usrp_sink : virtual public sync_block
58  {
59  public:
60  // gr::uhd::usrp_sink::sptr
62 
63  /*!
64  * \brief DEPRECATED Make a new USRP sink block using the deprecated io_type_t.
65  * \ingroup uhd_blk
66  *
67  * This function will be removed in the future. Please use the other make function,
68  * gr::uhd::usrp_sink::make(const ::uhd::device_addr_t, const ::uhd::stream_args_t, const std::string).
69  */
70  static sptr make(const ::uhd::device_addr_t &device_addr,
71  const ::uhd::io_type_t &io_type,
72  size_t num_channels);
73 
74  /*!
75  * \brief Make a new USRP sink block (usually a radio transmitter).
76  *
77  * The USRP sink block reads a stream and transmits the samples.
78  * The sink block also provides API calls for transmitter settings.
79  *
80  * \section uhd_tx_tagging TX Stream tagging
81  *
82  * The following tag keys will be consumed by the work function:
83  * - pmt::string_to_symbol("tx_sob")
84  * - pmt::string_to_symbol("tx_eob")
85  * - pmt::string_to_symbol("tx_time")
86  * - pmt::string_to_symbol("tx_freq")
87  * - pmt::string_to_symbol("tx_command")
88  * - pmt::string_to_symbol(tsb_tag_name)
89  *
90  * Any other tag will be ignored.
91  *
92  * The sob and eob (start and end of burst) tag values are pmt booleans.
93  * When present, burst tags should be set to true (pmt::PMT_T).
94  *
95  * If `tsb_tag_name` is not an empty string, all "tx_sob" and "tx_eob"
96  * tags will be ignored, and the input is assumed to a tagged stream,
97  * as described in \ref page_tagged_stream_blocks.
98  *
99  * If sob/eob tags or length tags are used, this block understands that
100  * the data is bursty, and will configure the USRP to make sure there's
101  * no underruns after transmitting the final sample of a burst.
102  *
103  * The timestamp tag value is a PMT tuple of the following:
104  * (uint64 seconds, double fractional seconds).
105  *
106  * The tx_freq tag has to be a double or a pair of form (channel, frequency),
107  * with frequency being a double and channel being an integer.
108  * This tag will trigger a tune command to the USRP
109  * to the given frequency, if possible. Note that oscillators need some time
110  * to stabilize after this! Don't expect clean data to be sent immediately after this command.
111  * If channel is omitted, and only a double is given, it will set this frequency to all
112  * channels.
113  *
114  * The command tag can carry a PMT command. See the following section.
115  *
116  * \section uhd_tx_commands Command interface
117  *
118  * There are two ways of passing commands to this block:
119  * 1. tx_command tag. The command is attached to a sample, and will executed
120  * before the sample is transmitted, and after the previous sample.
121  * 2. The 'command' message port. The command is executed asynchronously,
122  * as soon as possible.
123  *
124  * In both cases, the payload of the command is a PMT command, as described
125  * in Section \ref uhd_command_syntax.
126  *
127  * For a more general description of the gr-uhd components, see \ref page_uhd.
128  *
129  * \param device_addr the address to identify the hardware
130  * \param stream_args the IO format and channel specification
131  * \param tsb_tag_name the name of the tag identifying tagged stream length
132  * \return a new USRP sink block object
133  */
134  static sptr make(const ::uhd::device_addr_t &device_addr,
135  const ::uhd::stream_args_t &stream_args,
136  const std::string &tsb_tag_name = "");
137 
138  /*!
139  * Set the start time for outgoing samples.
140  * To control when samples are transmitted,
141  * set this value before starting the flow graph.
142  * The value is cleared after each run.
143  * When not specified, the start time will be:
144  * - Immediately for the one channel case
145  * - in the near future for multi-channel
146  *
147  * \param time the absolute time for transmission to begin
148  */
149  virtual void set_start_time(const ::uhd::time_spec_t &time) = 0;
150 
151  /*!
152  * Returns identifying information about this USRP's configuration.
153  * Returns motherboard ID, name, and serial.
154  * Returns daughterboard TX ID, subdev name and spec, serial, and antenna.
155  * \param chan channel index 0 to N-1
156  * \return TX info
157  */
158  virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
159 
160  /*!
161  * Set the frontend specification.
162  * \param spec the subdev spec markup string
163  * \param mboard the motherboard index 0 to M-1
164  */
165  virtual void set_subdev_spec(const std::string &spec, size_t mboard = 0) = 0;
166 
167  /*!
168  * Get the TX frontend specification.
169  * \param mboard the motherboard index 0 to M-1
170  * \return the frontend specification in use
171  */
172  virtual std::string get_subdev_spec (size_t mboard = 0) = 0;
173 
174  /*!
175  * Set the sample rate for the usrp device.
176  * \param rate a new rate in Sps
177  */
178  virtual void set_samp_rate(double rate) = 0;
179 
180  /*!
181  * Get the sample rate for the usrp device.
182  * This is the actual sample rate and may differ from the rate set.
183  * \return the actual rate in Sps
184  */
185  virtual double get_samp_rate(void) = 0;
186 
187  /*!
188  * Get the possible sample rates for the usrp device.
189  * \return a range of rates in Sps
190  */
191  virtual ::uhd::meta_range_t get_samp_rates(void) = 0;
192 
193  /*!
194  * Tune the usrp device to the desired center frequency.
195  * \param tune_request the tune request instructions
196  * \param chan the channel index 0 to N-1
197  * \return a tune result with the actual frequencies
198  */
199  virtual ::uhd::tune_result_t set_center_freq
200  (const ::uhd::tune_request_t tune_request, size_t chan = 0) = 0;
201 
202  /*!
203  * Tune the usrp device to the desired center frequency.
204  * This is a wrapper around set center freq so that in this case,
205  * the user can pass a single frequency in the call through swig.
206  * \param freq the desired frequency in Hz
207  * \param chan the channel index 0 to N-1
208  * \return a tune result with the actual frequencies
209  */
210  ::uhd::tune_result_t set_center_freq(double freq, size_t chan = 0)
211  {
212  return set_center_freq(::uhd::tune_request_t(freq), chan);
213  }
214 
215  /*!
216  * Get the center frequency.
217  * \param chan the channel index 0 to N-1
218  * \return the frequency in Hz
219  */
220  virtual double get_center_freq(size_t chan = 0) = 0;
221 
222  /*!
223  * Get the tunable frequency range.
224  * \param chan the channel index 0 to N-1
225  * \return the frequency range in Hz
226  */
227  virtual ::uhd::freq_range_t get_freq_range(size_t chan = 0) = 0;
228 
229  /*!
230  * Set the gain for the dboard.
231  * \param gain the gain in dB
232  * \param chan the channel index 0 to N-1
233  */
234  virtual void set_gain(double gain, size_t chan = 0) = 0;
235 
236  /*!
237  * Set the named gain on the dboard.
238  * \param gain the gain in dB
239  * \param name the name of the gain stage
240  * \param chan the channel index 0 to N-1
241  */
242  virtual void set_gain(double gain,
243  const std::string &name,
244  size_t chan = 0) = 0;
245 
246  /*!
247  * Set the normalized gain.
248  *
249  * The normalized gain is always in [0, 1], regardless of the device.
250  * 0 corresponds to minimum gain (usually 0 dB, but make sure to read the device
251  * notes in the UHD manual) and 1 corresponds to maximum gain.
252  * This will work for any UHD device. Use get_gain() to see which dB value
253  * the normalized gain value corresponds to.
254  *
255  * Note that it is not possible to specify a gain name for this function.
256  *
257  * \throws A runtime_error if \p norm_gain is not within the valid range.
258  *
259  * \param norm_gain the gain in fractions of the gain range (must be 0 <= norm_gain <= 1)
260  * \param chan the channel index 0 to N-1
261  */
262  virtual void set_normalized_gain(double norm_gain, size_t chan = 0) = 0;
263 
264  /*!
265  * Get the actual dboard gain setting.
266  * \param chan the channel index 0 to N-1
267  * \return the actual gain in dB
268  */
269  virtual double get_gain(size_t chan = 0) = 0;
270 
271  /*!
272  * Get the actual dboard gain setting of named stage.
273  * \param name the name of the gain stage
274  * \param chan the channel index 0 to N-1
275  * \return the actual gain in dB
276  */
277  virtual double get_gain(const std::string &name,
278  size_t chan = 0) = 0;
279 
280  /*!
281  * Returns the normalized gain.
282  *
283  * The normalized gain is always in [0, 1], regardless of the device.
284  * See also set_normalized_gain().
285  *
286  * Note that it is not possible to specify a gain name for this function,
287  * the result is over the entire gain chain.
288  *
289  * \param chan the channel index 0 to N-1
290  */
291  virtual double get_normalized_gain(size_t chan = 0) = 0;
292 
293  /*!
294  * Get the actual dboard gain setting of named stage.
295  * \param chan the channel index 0 to N-1
296  * \return the actual gain in dB
297  */
298  virtual std::vector<std::string> get_gain_names(size_t chan = 0) = 0;
299 
300  /*!
301  * Get the settable gain range.
302  * \param chan the channel index 0 to N-1
303  * \return the gain range in dB
304  */
305  virtual ::uhd::gain_range_t get_gain_range(size_t chan = 0) = 0;
306 
307  /*!
308  * Get the settable gain range.
309  * \param name the name of the gain stage
310  * \param chan the channel index 0 to N-1
311  * \return the gain range in dB
312  */
313  virtual ::uhd::gain_range_t get_gain_range(const std::string &name,
314  size_t chan = 0) = 0;
315 
316  /*!
317  * Set the antenna to use.
318  * \param ant the antenna string
319  * \param chan the channel index 0 to N-1
320  */
321  virtual void set_antenna(const std::string &ant,
322  size_t chan = 0) = 0;
323 
324  /*!
325  * Get the antenna in use.
326  * \param chan the channel index 0 to N-1
327  * \return the antenna string
328  */
329  virtual std::string get_antenna(size_t chan = 0) = 0;
330 
331  /*!
332  * Get a list of possible antennas.
333  * \param chan the channel index 0 to N-1
334  * \return a vector of antenna strings
335  */
336  virtual std::vector<std::string> get_antennas(size_t chan = 0) = 0;
337 
338  /*!
339  * Set the bandpass filter on the RF frontend.
340  * \param bandwidth the filter bandwidth in Hz
341  * \param chan the channel index 0 to N-1
342  */
343  virtual void set_bandwidth(double bandwidth, size_t chan = 0) = 0;
344 
345  /*!
346  * Get the bandpass filter setting on the RF frontend.
347  * \param chan the channel index 0 to N-1
348  * \return bandwidth of the filter in Hz
349  */
350  virtual double get_bandwidth(size_t chan = 0) = 0;
351 
352  /*!
353  * Get the bandpass filter range of the RF frontend.
354  * \param chan the channel index 0 to N-1
355  * \return the range of the filter bandwidth in Hz
356  */
357  virtual ::uhd::freq_range_t get_bandwidth_range(size_t chan = 0) = 0;
358 
359  /*!
360  * Set a constant DC offset value.
361  * The value is complex to control both I and Q.
362  * \param offset the dc offset (1.0 is full-scale)
363  * \param chan the channel index 0 to N-1
364  */
365  virtual void set_dc_offset(const std::complex<double> &offset,
366  size_t chan = 0) = 0;
367 
368  /*!
369  * Set the RX frontend IQ imbalance correction.
370  * Use this to adjust the magnitude and phase of I and Q.
371  *
372  * \param correction the complex correction (1.0 is full-scale)
373  * \param chan the channel index 0 to N-1
374  */
375  virtual void set_iq_balance(const std::complex<double> &correction,
376  size_t chan = 0) = 0;
377 
378  /*!
379  * Get an RF frontend sensor value.
380  * \param name the name of the sensor
381  * \param chan the channel index 0 to N-1
382  * \return a sensor value object
383  */
384  virtual ::uhd::sensor_value_t get_sensor(const std::string &name,
385  size_t chan = 0) = 0;
386 
387  /*!
388  * Get a list of possible RF frontend sensor names.
389  * \param chan the channel index 0 to N-1
390  * \return a vector of sensor names
391  */
392  virtual std::vector<std::string> get_sensor_names(size_t chan = 0) = 0;
393 
394  //! DEPRECATED use get_sensor
395  ::uhd::sensor_value_t get_dboard_sensor(const std::string &name,
396  size_t chan = 0)
397  {
398  return this->get_sensor(name, chan);
399  }
400 
401  //! DEPRECATED use get_sensor_names
402  std::vector<std::string> get_dboard_sensor_names(size_t chan = 0)
403  {
404  return this->get_sensor_names(chan);
405  }
406 
407  /*!
408  * Get a motherboard sensor value.
409  * \param name the name of the sensor
410  * \param mboard the motherboard index 0 to M-1
411  * \return a sensor value object
412  */
413  virtual ::uhd::sensor_value_t get_mboard_sensor(const std::string &name,
414  size_t mboard = 0) = 0;
415 
416  /*!
417  * Get a list of possible motherboard sensor names.
418  * \param mboard the motherboard index 0 to M-1
419  * \return a vector of sensor names
420  */
421  virtual std::vector<std::string> get_mboard_sensor_names(size_t mboard = 0) = 0;
422 
423  /*!
424  * Set the clock configuration.
425  * DEPRECATED for set_time/clock_source.
426  * \param clock_config the new configuration
427  * \param mboard the motherboard index 0 to M-1
428  */
429  virtual void set_clock_config(const ::uhd::clock_config_t &clock_config,
430  size_t mboard = 0) = 0;
431 
432  /*!
433  * Set the time source for the usrp device.
434  * This sets the method of time synchronization,
435  * typically a pulse per second or an encoded time.
436  * Typical options for source: external, MIMO.
437  * \param source a string representing the time source
438  * \param mboard which motherboard to set the config
439  */
440  virtual void set_time_source(const std::string &source,
441  const size_t mboard = 0) = 0;
442 
443  /*!
444  * Get the currently set time source.
445  * \param mboard which motherboard to get the config
446  * \return the string representing the time source
447  */
448  virtual std::string get_time_source(const size_t mboard) = 0;
449 
450  /*!
451  * Get a list of possible time sources.
452  * \param mboard which motherboard to get the list
453  * \return a vector of strings for possible settings
454  */
455  virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0;
456 
457  /*!
458  * Set the clock source for the usrp device.
459  * This sets the source for a 10 Mhz reference clock.
460  * Typical options for source: internal, external, MIMO.
461  * \param source a string representing the clock source
462  * \param mboard which motherboard to set the config
463  */
464  virtual void set_clock_source(const std::string &source,
465  const size_t mboard = 0) = 0;
466 
467  /*!
468  * Get the currently set clock source.
469  * \param mboard which motherboard to get the config
470  * \return the string representing the clock source
471  */
472  virtual std::string get_clock_source(const size_t mboard) = 0;
473 
474  /*!
475  * Get a list of possible clock sources.
476  * \param mboard which motherboard to get the list
477  * \return a vector of strings for possible settings
478  */
479  virtual std::vector<std::string> get_clock_sources(const size_t mboard) = 0;
480 
481  /*!
482  * Get the master clock rate.
483  * \param mboard the motherboard index 0 to M-1
484  * \return the clock rate in Hz
485  */
486  virtual double get_clock_rate(size_t mboard = 0) = 0;
487 
488  /*!
489  * Set the master clock rate.
490  * \param rate the new rate in Hz
491  * \param mboard the motherboard index 0 to M-1
492  */
493  virtual void set_clock_rate(double rate, size_t mboard = 0) = 0;
494 
495  /*!
496  * Get the current time registers.
497  * \param mboard the motherboard index 0 to M-1
498  * \return the current usrp time
499  */
500  virtual ::uhd::time_spec_t get_time_now(size_t mboard = 0) = 0;
501 
502  /*!
503  * Get the time when the last pps pulse occured.
504  * \param mboard the motherboard index 0 to M-1
505  * \return the current usrp time
506  */
507  virtual ::uhd::time_spec_t get_time_last_pps(size_t mboard = 0) = 0;
508 
509  /*!
510  * Sets the time registers immediately.
511  * \param time_spec the new time
512  * \param mboard the motherboard index 0 to M-1
513  */
514  virtual void set_time_now(const ::uhd::time_spec_t &time_spec, size_t mboard = 0) = 0;
515 
516  /*!
517  * Set the time registers at the next pps.
518  * \param time_spec the new time
519  */
520  virtual void set_time_next_pps(const ::uhd::time_spec_t &time_spec) = 0;
521 
522  /*!
523  * Sync the time registers with an unknown pps edge.
524  * \param time_spec the new time
525  */
526  virtual void set_time_unknown_pps(const ::uhd::time_spec_t &time_spec) = 0;
527 
528  /*!
529  * Set the time at which the control commands will take effect.
530  *
531  * A timed command will back-pressure all subsequent timed commands,
532  * assuming that the subsequent commands occur within the time-window.
533  * If the time spec is late, the command will be activated upon arrival.
534  *
535  * \param time_spec the time at which the next command will activate
536  * \param mboard which motherboard to set the config
537  */
538  virtual void set_command_time(const ::uhd::time_spec_t &time_spec,
539  size_t mboard = 0) = 0;
540 
541  /*!
542  * Clear the command time so future commands are sent ASAP.
543  *
544  * \param mboard which motherboard to set the config
545  */
546  virtual void clear_command_time(size_t mboard = 0) = 0;
547 
548  /*!
549  * Get access to the underlying uhd dboard iface object.
550  * \return the dboard_iface object
551  */
552  virtual ::uhd::usrp::dboard_iface::sptr get_dboard_iface(size_t chan = 0) = 0;
553 
554  /*!
555  * Get access to the underlying uhd device object.
556  *
557  * NOTE: This function is only available in C++.
558  * \return the multi usrp device object
559  */
560  virtual ::uhd::usrp::multi_usrp::sptr get_device(void) = 0;
561 
562  /*!
563  * Perform write on the user configuration register bus. These
564  * only exist if the user has implemented custom setting
565  * registers in the device FPGA.
566  * \param addr 8-bit register address
567  * \param data 32-bit register value
568  * \param mboard which motherboard to set the user register
569  */
570  virtual void set_user_register(const uint8_t addr,
571  const uint32_t data,
572  size_t mboard = 0) = 0;
573 
574  /*!
575  * Update the stream args for this device.
576  *
577  * This update will only take effect after a restart of the
578  * streaming, or before streaming and after construction.
579  * This will also delete the current streamer.
580  * Note you cannot change the I/O signature of this block using
581  * this function, or it will throw.
582  *
583  * It is possible to leave the 'channels' fields of \p stream_args
584  * unset. In this case, the previous channels field is used.
585  *
586  * \param stream_args New stream args.
587  * \throws std::runtime_error if new settings are invalid.
588  */
589  virtual void set_stream_args(const ::uhd::stream_args_t &stream_args) = 0;
590  };
591 
592  } /* namespace uhd */
593 } /* namespace gr */
594 
595 #endif /* INCLUDED_GR_UHD_USRP_SINK_H */
std::vector< std::string > get_dboard_sensor_names(size_t chan=0)
DEPRECATED use get_sensor_names.
Definition: usrp_sink.h:402
::uhd::tune_result_t set_center_freq(double freq, size_t chan=0)
Definition: usrp_sink.h:210
::uhd::sensor_value_t get_dboard_sensor(const std::string &name, size_t chan=0)
DEPRECATED use get_sensor.
Definition: usrp_sink.h:395
Definition: usrp_sink.h:57
unsigned char uint8_t
Definition: stdint.h:78
shared_ptr documentation stub
Definition: shared_ptr_docstub.h:15
std::string otw_format
Definition: usrp_sink.h:42
Definition: usrp_sink.h:32
unsigned int uint32_t
Definition: stdint.h:80
std::string cpu_format
Definition: usrp_sink.h:41
boost::shared_ptr< usrp_sink > sptr
Definition: usrp_sink.h:61
Include this header to use the message passing features.
Definition: logger.h:129
stream_args_t(const std::string &cpu="", const std::string &otw="")
Definition: usrp_sink.h:35
synchronous 1:1 input to output with historyOverride work to provide the signal processing implementa...
Definition: sync_block.h:37
device_addr_t args
Definition: usrp_sink.h:43
Definition: usrp_sink.h:33
#define GR_UHD_API
Definition: gr-uhd/include/gnuradio/uhd/api.h:30
VOLK_API $kern pname $kern name
A function pointer to the dispatcher implementation.
std::vector< size_t > channels
Definition: usrp_sink.h:44