GNU Radio Manual and C++ API Reference  3.8.5.0
The Free & Open Software Radio Ecosystem
usrp_block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2015,2019 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_BLOCK_H
24 #define INCLUDED_GR_UHD_USRP_BLOCK_H
25 
26 #include <gnuradio/sync_block.h>
27 #include <gnuradio/uhd/api.h>
28 #include <uhd/usrp/multi_usrp.hpp>
29 
30 namespace gr {
31 namespace uhd {
32 
48 
51 
52 /*! Base class for USRP blocks.
53  * \ingroup uhd_blk
54  *
55  * Note that many of the functions defined here differ between
56  * Rx and Tx configurations. As an example, set_center_freq()
57  * will set the Rx frequency for a usrp_source object, and the
58  * Tx frequency on a usrp_sink object.
59  */
61 {
62 protected:
63  usrp_block(){}; // For virtual sub-classing
64  usrp_block(const std::string& name,
65  gr::io_signature::sptr input_signature,
66  gr::io_signature::sptr output_signature);
67 
68 public:
69  /*!
70  * Set the frontend specification.
71  *
72  * \param spec the subdev spec markup string
73  * \param mboard the motherboard index 0 to M-1
74  */
75  virtual void set_subdev_spec(const std::string& spec, size_t mboard = 0) = 0;
76 
77  /*!
78  * Get the frontend specification.
79  *
80  * \param mboard the motherboard index 0 to M-1
81  * \return the frontend specification in use
82  */
83  virtual std::string get_subdev_spec(size_t mboard = 0) = 0;
84 
85  /*!
86  * Return the number of motherboards in this configuration.
87  */
88  virtual size_t get_num_mboards() = 0;
89 
90  /*!
91  * Set the sample rate for this connection to the USRP.
92  *
93  * \param rate a new rate in Sps
94  */
95  virtual void set_samp_rate(double rate) = 0;
96 
97  /*!
98  * Get the sample rate for this connection to the USRP.
99  * This is the actual sample rate and may differ from the rate set.
100  *
101  * \return the actual rate in Sps
102  */
103  virtual double get_samp_rate(void) = 0;
104 
105  /*!
106  * Get the possible sample rates for this connection.
107  *
108  * \return a range of rates in Sps
109  */
110  virtual ::uhd::meta_range_t get_samp_rates(void) = 0;
111 
112  /*!
113  * Tune the selected channel to the desired center frequency.
114  *
115  * \param tune_request the tune request instructions
116  * \param chan the channel index 0 to N-1
117  * \return a tune result with the actual frequencies
118  */
119  virtual ::uhd::tune_result_t set_center_freq(const ::uhd::tune_request_t tune_request,
120  size_t chan = 0) = 0;
121 
122  /*!
123  * Tune the selected channel to the desired center frequency.
124  *
125  * This is a wrapper around set_center_freq() so that in this case,
126  * the user can pass a single frequency in the call instead of
127  * having to generate a tune_request_t object.
128  *
129  * \param freq the desired frequency in Hz
130  * \param chan the channel index 0 to N-1
131  * \return a tune result with the actual frequencies
132  */
133  ::uhd::tune_result_t set_center_freq(double freq, size_t chan = 0)
134  {
135  return set_center_freq(::uhd::tune_request_t(freq), chan);
136  }
137 
138  /*!
139  * Get the center frequency.
140  *
141  * \param chan the channel index 0 to N-1
142  * \return the frequency in Hz
143  */
144  virtual double get_center_freq(size_t chan = 0) = 0;
145 
146  /*!
147  * Get the tunable frequency range.
148  *
149  * \param chan the channel index 0 to N-1
150  * \return the frequency range in Hz
151  */
152  virtual ::uhd::freq_range_t get_freq_range(size_t chan = 0) = 0;
153 
154  /*!
155  * Set the gain for the selected channel.
156  *
157  * \param gain the gain in dB
158  * \param chan the channel index 0 to N-1
159  */
160  virtual void set_gain(double gain, size_t chan = 0) = 0;
161 
162  /*!
163  * Set the named gain on the dboard.
164  *
165  * \param gain the gain in dB
166  * \param name the name of the gain stage
167  * \param chan the channel index 0 to N-1
168  */
169  virtual void set_gain(double gain, const std::string& name, size_t chan = 0) = 0;
170 
171  /*!
172  * Set the normalized gain.
173  *
174  * The normalized gain is always in [0, 1], regardless of the device.
175  * 0 corresponds to minimum gain (usually 0 dB, but make sure to read the device
176  * notes in the UHD manual) and 1 corresponds to maximum gain.
177  * This will work for any UHD device. Use get_gain() to see which dB value
178  * the normalized gain value corresponds to.
179  *
180  * Note that it is not possible to specify a gain name for this function.
181  *
182  * \throws A runtime_error if \p norm_gain is not within the valid range.
183  *
184  * \param norm_gain the gain in fractions of the gain range (must be 0 <= norm_gain <=
185  * 1) \param chan the channel index 0 to N-1
186  */
187  virtual void set_normalized_gain(double norm_gain, size_t chan = 0) = 0;
188 
189  /*!
190  * Get the actual dboard gain setting.
191  *
192  * \param chan the channel index 0 to N-1
193  * \return the actual gain in dB
194  */
195  virtual double get_gain(size_t chan = 0) = 0;
196 
197  /*!
198  * Get the actual dboard gain setting of named stage.
199  *
200  * \param name the name of the gain stage
201  * \param chan the channel index 0 to N-1
202  * \return the actual gain in dB
203  */
204  virtual double get_gain(const std::string& name, size_t chan = 0) = 0;
205 
206  /*!
207  * Returns the normalized gain.
208  *
209  * The normalized gain is always in [0, 1], regardless of the device.
210  * See also set_normalized_gain().
211  *
212  * Note that it is not possible to specify a gain name for
213  * this function, the result is over the entire gain chain.
214  *
215  * \param chan the channel index 0 to N-1
216  */
217  virtual double get_normalized_gain(size_t chan = 0) = 0;
218 
219  /*!
220  * Get the actual dboard gain setting of named stage.
221  *
222  * \param chan the channel index 0 to N-1
223  * \return the actual gain in dB
224  */
225  virtual std::vector<std::string> get_gain_names(size_t chan = 0) = 0;
226 
227  /*!
228  * Get the settable gain range.
229  *
230  * \param chan the channel index 0 to N-1
231  * \return the gain range in dB
232  */
233  virtual ::uhd::gain_range_t get_gain_range(size_t chan = 0) = 0;
234 
235  /*!
236  * Get the settable gain range.
237  *
238  * \param name the name of the gain stage
239  * \param chan the channel index 0 to N-1
240  * \return the gain range in dB
241  */
242  virtual ::uhd::gain_range_t get_gain_range(const std::string& name,
243  size_t chan = 0) = 0;
244 
245  /*!
246  * Set the antenna to use for a given channel.
247  *
248  * \param ant the antenna string
249  * \param chan the channel index 0 to N-1
250  */
251  virtual void set_antenna(const std::string& ant, size_t chan = 0) = 0;
252 
253  /*!
254  * Get the antenna in use.
255  *
256  * \param chan the channel index 0 to N-1
257  * \return the antenna string
258  */
259  virtual std::string get_antenna(size_t chan = 0) = 0;
260 
261  /*!
262  * Get a list of possible antennas on a given channel.
263  *
264  * \param chan the channel index 0 to N-1
265  * \return a vector of antenna strings
266  */
267  virtual std::vector<std::string> get_antennas(size_t chan = 0) = 0;
268 
269  /*!
270  * Set the bandpass filter on the RF frontend.
271  *
272  * \param bandwidth the filter bandwidth in Hz
273  * \param chan the channel index 0 to N-1
274  */
275  virtual void set_bandwidth(double bandwidth, size_t chan = 0) = 0;
276 
277  /*!
278  * Get the bandpass filter setting on the RF frontend.
279  *
280  * \param chan the channel index 0 to N-1
281  * \return bandwidth of the filter in Hz
282  */
283  virtual double get_bandwidth(size_t chan = 0) = 0;
284 
285  /*!
286  * Get the bandpass filter range of the RF frontend.
287  *
288  * \param chan the channel index 0 to N-1
289  * \return the range of the filter bandwidth in Hz
290  */
291  virtual ::uhd::freq_range_t get_bandwidth_range(size_t chan = 0) = 0;
292 
293  /*!
294  * Get an RF frontend sensor value.
295  * \param name the name of the sensor
296  * \param chan the channel index 0 to N-1
297  * \return a sensor value object
298  */
299  virtual ::uhd::sensor_value_t get_sensor(const std::string& name,
300  size_t chan = 0) = 0;
301 
302  /*!
303  * Get a list of possible RF frontend sensor names.
304  * \param chan the channel index 0 to N-1
305  * \return a vector of sensor names
306  */
307  virtual std::vector<std::string> get_sensor_names(size_t chan = 0) = 0;
308 
309  //! DEPRECATED use get_sensor
310  ::uhd::sensor_value_t get_dboard_sensor(const std::string& name, size_t chan = 0)
311  {
312  return this->get_sensor(name, chan);
313  }
314 
315  //! DEPRECATED use get_sensor_names
316  std::vector<std::string> get_dboard_sensor_names(size_t chan = 0)
317  {
318  return this->get_sensor_names(chan);
319  }
320 
321  /*!
322  * Get a motherboard sensor value.
323  *
324  * \param name the name of the sensor
325  * \param mboard the motherboard index 0 to M-1
326  * \return a sensor value object
327  */
328  virtual ::uhd::sensor_value_t get_mboard_sensor(const std::string& name,
329  size_t mboard = 0) = 0;
330 
331  /*!
332  * Get a list of possible motherboard sensor names.
333  *
334  * \param mboard the motherboard index 0 to M-1
335  * \return a vector of sensor names
336  */
337  virtual std::vector<std::string> get_mboard_sensor_names(size_t mboard = 0) = 0;
338 
339  /*!
340  * Get the currently set time source.
341  *
342  * \param mboard which motherboard to get the config
343  * \return the string representing the time source
344  */
345  virtual std::string get_time_source(const size_t mboard) = 0;
346 
347  /*!
348  * Get a list of possible time sources.
349  *
350  * \param mboard which motherboard to get the list
351  * \return a vector of strings for possible settings
352  */
353  virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0;
354 
355  /*!
356  * Set the clock source for the usrp device.
357  *
358  * This sets the source for a 10 MHz reference clock.
359  * Typical options for source: internal, external, MIMO.
360  *
361  * \param source a string representing the clock source
362  * \param mboard which motherboard to set the config
363  */
364  virtual void set_clock_source(const std::string& source, const size_t mboard = 0) = 0;
365 
366  /*!
367  * Get the currently set clock source.
368  *
369  * \param mboard which motherboard to get the config
370  * \return the string representing the clock source
371  */
372  virtual std::string get_clock_source(const size_t mboard) = 0;
373 
374  /*!
375  * Get a list of possible clock sources.
376  *
377  * \param mboard which motherboard to get the list
378  * \return a vector of strings for possible settings
379  */
380  virtual std::vector<std::string> get_clock_sources(const size_t mboard) = 0;
381 
382  /*!
383  * Get the master clock rate.
384  *
385  * \param mboard the motherboard index 0 to M-1
386  * \return the clock rate in Hz
387  */
388  virtual double get_clock_rate(size_t mboard = 0) = 0;
389 
390  /*!
391  * Set the master clock rate.
392  *
393  * \param rate the new rate in Hz
394  * \param mboard the motherboard index 0 to M-1
395  */
396  virtual void set_clock_rate(double rate, size_t mboard = 0) = 0;
397 
398  /*!
399  * Get the current time registers.
400  *
401  * \param mboard the motherboard index 0 to M-1
402  * \return the current usrp time
403  */
404  virtual ::uhd::time_spec_t get_time_now(size_t mboard = 0) = 0;
405 
406  /*!
407  * Get the time when the last pps pulse occurred.
408  * \param mboard the motherboard index 0 to M-1
409  * \return the current usrp time
410  */
411  virtual ::uhd::time_spec_t get_time_last_pps(size_t mboard = 0) = 0;
412 
413  /*!
414  * Sets the time registers immediately.
415  * \param time_spec the new time
416  * \param mboard the motherboard index 0 to M-1
417  */
418  virtual void set_time_now(const ::uhd::time_spec_t& time_spec, size_t mboard = 0) = 0;
419 
420  /*!
421  * Set the time registers at the next pps.
422  * \param time_spec the new time
423  */
424  virtual void set_time_next_pps(const ::uhd::time_spec_t& time_spec) = 0;
425 
426  /*!
427  * Sync the time registers with an unknown pps edge.
428  * \param time_spec the new time
429  */
430  virtual void set_time_unknown_pps(const ::uhd::time_spec_t& time_spec) = 0;
431 
432  /*!
433  * Set the time at which the control commands will take effect.
434  *
435  * A timed command will back-pressure all subsequent timed commands,
436  * assuming that the subsequent commands occur within the time-window.
437  * If the time spec is late, the command will be activated upon arrival.
438  *
439  * \param time_spec the time at which the next command will activate
440  * \param mboard which motherboard to set the config
441  */
442  virtual void set_command_time(const ::uhd::time_spec_t& time_spec,
443  size_t mboard = 0) = 0;
444 
445  /*!
446  * Clear the command time so future commands are sent ASAP.
447  *
448  * \param mboard which motherboard to set the config
449  */
450  virtual void clear_command_time(size_t mboard = 0) = 0;
451 
452  /*!
453  * Get access to the underlying uhd dboard iface object.
454  *
455  * \return the dboard_iface object
456  */
457  virtual ::uhd::usrp::dboard_iface::sptr get_dboard_iface(size_t chan = 0) = 0;
458 
459  /*!
460  * Get access to the underlying uhd device object.
461  *
462  * NOTE: This function is only available in C++.
463  * \return the multi usrp device object
464  */
465  virtual ::uhd::usrp::multi_usrp::sptr get_device(void) = 0;
466 
467  /*!
468  * Perform write on the user configuration register bus. These
469  * only exist if the user has implemented custom setting
470  * registers in the device FPGA.
471  *
472  * \param addr 8-bit register address
473  * \param data 32-bit register value
474  * \param mboard which motherboard to set the user register
475  */
476  virtual void
477  set_user_register(const uint8_t addr, const uint32_t data, size_t mboard = 0) = 0;
478 
479  /*!
480  * Set the time source for the USRP device.
481  *
482  * This sets the method of time synchronization,
483  * typically a pulse per second or an encoded time.
484  * Typical options for source: external, MIMO.
485  * \param source a string representing the time source
486  * \param mboard which motherboard to set the config
487  */
488  virtual void set_time_source(const std::string& source, const size_t mboard = 0) = 0;
489 
490  /*!
491  * Update the stream args for this device.
492  *
493  * This update will only take effect after a restart of the
494  * streaming, or before streaming and after construction.
495  * This will also delete the current streamer.
496  * Note you cannot change the I/O signature of this block using
497  * this function, or it will throw.
498  *
499  * It is possible to leave the 'channels' fields of \p stream_args
500  * unset. In this case, the previous channels field is used.
501  *
502  * \param stream_args New stream args.
503  * \throws std::runtime_error if new settings are invalid.
504  */
505  virtual void set_stream_args(const ::uhd::stream_args_t& stream_args) = 0;
506 
507  /*******************************************************************
508  * GPIO methods
509  ******************************************************************/
510  /*!
511  * Enumerate GPIO banks on the current device.
512  * \param mboard the motherboard index 0 to M-1
513  * \return a list of string for each bank name
514  */
515  virtual std::vector<std::string> get_gpio_banks(const size_t mboard) = 0;
516 
517  /*!
518  * Set a GPIO attribute on a particular GPIO bank.
519  * Possible attribute names:
520  * - CTRL - 1 for ATR mode 0 for GPIO mode
521  * - DDR - 1 for output 0 for input
522  * - OUT - GPIO output level (not ATR mode)
523  * - ATR_0X - ATR idle state
524  * - ATR_RX - ATR receive only state
525  * - ATR_TX - ATR transmit only state
526  * - ATR_XX - ATR full duplex state
527  * \param bank the name of a GPIO bank
528  * \param attr the name of a GPIO attribute
529  * \param value the new value for this GPIO bank
530  * \param mask the bit mask to effect which pins are changed
531  * \param mboard the motherboard index 0 to M-1
532  */
533  virtual void set_gpio_attr(const std::string& bank,
534  const std::string& attr,
535  const boost::uint32_t value,
536  const boost::uint32_t mask = 0xffffffff,
537  const size_t mboard = 0) = 0;
538 
539  /*!
540  * Get a GPIO attribute on a particular GPIO bank.
541  * Possible attribute names:
542  * - CTRL - 1 for ATR mode 0 for GPIO mode
543  * - DDR - 1 for output 0 for input
544  * - OUT - GPIO output level (not ATR mode)
545  * - ATR_0X - ATR idle state
546  * - ATR_RX - ATR receive only state
547  * - ATR_TX - ATR transmit only state
548  * - ATR_XX - ATR full duplex state
549  * - READBACK - readback input GPIOs
550  * \param bank the name of a GPIO bank
551  * \param attr the name of a GPIO attribute
552  * \param mboard the motherboard index 0 to M-1
553  * \return the value set for this attribute
554  */
555  virtual boost::uint32_t get_gpio_attr(const std::string& bank,
556  const std::string& attr,
557  const size_t mboard = 0) = 0;
558 
559  /*!
560  * Enumerate the available filters in the signal path.
561  * \param search_mask
562  * \parblock
563  * Select only certain filter names by specifying this search mask.
564  *
565  * E.g. if search mask is set to "rx_frontends/A" only filter names including
566  * that string will be returned. \endparblock \return a vector of strings
567  * representing the selected filter names.
568  */
569  virtual std::vector<std::string>
570  get_filter_names(const std::string& search_mask = "") = 0;
571 
572  /*!
573  * Write back a filter obtained by get_filter() to the signal path.
574  * This filter can be a modified version of the originally returned one.
575  * The information about Rx or Tx is contained in the path parameter.
576  * \param path the name of the filter as returned from get_filter_names().
577  * \param filter the filter_info_base::sptr of the filter object to be written
578  */
579  virtual void set_filter(const std::string& path,
580  ::uhd::filter_info_base::sptr filter) = 0;
581 
582  /*!
583  * Return the filter object for the given name.
584  * @param path the name of the filter as returned from get_filter_names()
585  * @return the filter object
586  */
587  virtual ::uhd::filter_info_base::sptr get_filter(const std::string& path) = 0;
588 };
589 
590 } /* namespace uhd */
591 } /* namespace gr */
592 
593 #endif /* INCLUDED_GR_UHD_USRP_BLOCK_H */
GR_UHD_API const pmt::pmt_t cmd_mboard_key()
boost::shared_ptr< io_signature > sptr
Definition: io_signature.h:46
Definition: usrp_block.h:60
GR_UHD_API const pmt::pmt_t cmd_tune_key()
boost::shared_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting). See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
Definition: pmt.h:96
GR_UHD_API const pmt::pmt_t cmd_gpio_key()
GR_UHD_API const pmt::pmt_t ant_direction_rx()
GR_UHD_API const pmt::pmt_t cmd_bandwidth_key()
GR_UHD_API const pmt::pmt_t cmd_lo_freq_key()
::uhd::tune_result_t set_center_freq(double freq, size_t chan=0)
Definition: usrp_block.h:133
GR_UHD_API const pmt::pmt_t ant_direction_tx()
usrp_block()
Definition: usrp_block.h:63
GR_UHD_API const pmt::pmt_t cmd_tag_key()
GNU Radio logging wrapper for log4cpp library (C++ port of log4j)
Definition: basic_block.h:46
GR_UHD_API const pmt::pmt_t cmd_dsp_freq_key()
synchronous 1:1 input to output with historyOverride work to provide the signal processing implementa...
Definition: sync_block.h:37
GR_UHD_API const pmt::pmt_t cmd_lo_offset_key()
GR_UHD_API const pmt::pmt_t cmd_direction_key()
#define GR_UHD_API
Definition: gr-uhd/include/gnuradio/uhd/api.h:30
GR_UHD_API const pmt::pmt_t cmd_gain_key()
GR_UHD_API const pmt::pmt_t cmd_chan_key()
GR_UHD_API const pmt::pmt_t cmd_antenna_key()
GR_UHD_API const pmt::pmt_t cmd_time_key()
std::vector< std::string > get_dboard_sensor_names(size_t chan=0)
DEPRECATED use get_sensor_names.
Definition: usrp_block.h:316
::uhd::sensor_value_t get_dboard_sensor(const std::string &name, size_t chan=0)
DEPRECATED use get_sensor.
Definition: usrp_block.h:310
GR_UHD_API const pmt::pmt_t cmd_rate_key()
GR_UHD_API const pmt::pmt_t cmd_freq_key()