GNU Radio 3.7.1 C++ API
usrp_source.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2010-2013 Free Software Foundation, Inc.
00004  *
00005  * This file is part of GNU Radio
00006  *
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  *
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef INCLUDED_GR_UHD_USRP_SOURCE_H
00024 #define INCLUDED_GR_UHD_USRP_SOURCE_H
00025 
00026 #include <gnuradio/uhd/api.h>
00027 #include <gnuradio/sync_block.h>
00028 #include <uhd/usrp/multi_usrp.hpp>
00029 
00030 #ifndef INCLUDED_UHD_STREAM_HPP
00031 namespace uhd {
00032   struct GR_UHD_API stream_args_t
00033   {
00034     stream_args_t(const std::string &cpu = "",
00035                   const std::string &otw = "")
00036       {
00037         cpu_format = cpu;
00038         otw_format = otw;
00039       }
00040     std::string cpu_format;
00041     std::string otw_format;
00042     device_addr_t args;
00043     std::vector<size_t> channels;
00044   };
00045 }
00046 #  define INCLUDED_UHD_STREAM_HPP
00047 #else
00048 #  define GR_UHD_USE_STREAM_API
00049 #endif
00050 
00051 namespace gr {
00052   namespace uhd {
00053 
00054     class uhd_usrp_source;
00055 
00056     class GR_UHD_API usrp_source : virtual public sync_block
00057     {
00058     public:
00059       // gr::uhd::usrp_source::sptr
00060       typedef boost::shared_ptr<usrp_source> sptr;
00061 
00062       /*!
00063        * \brief Make a new USRP source block.
00064        * \ingroup uhd_blk
00065        *
00066        * The USRP source block receives samples and writes to a stream.
00067        * The source block also provides API calls for receiver settings.
00068        *
00069        * RX Stream tagging:
00070        *
00071        * The following tag keys will be produced by the work function:
00072        *  - pmt::string_to_symbol("rx_time")
00073        *  - pmt::string_to_symbol("rx_rate")
00074        *  - pmt::string_to_symbol("rx_freq")
00075        *
00076        * The timstamp tag value is a pmt tuple of the following:
00077        * (uint64 seconds, and double fractional seconds).
00078        * A timestamp tag is produced at start() and after overflows.
00079        *
00080        * The sample rate and center frequency tags are doubles,
00081        * representing the sample rate in Sps and frequency in Hz.
00082        * These tags are produced upon the user changing parameters.
00083        *
00084        * See the UHD manual for more detailed documentation:
00085        * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
00086        *
00087        * \param device_addr the address to identify the hardware
00088        * \param io_type the desired output data type
00089        * \param num_channels number of stream from the device
00090        * \return a new USRP source block object
00091        */
00092       static sptr make(const ::uhd::device_addr_t &device_addr,
00093                        const ::uhd::io_type_t &io_type,
00094                        size_t num_channels);
00095 
00096       /*!
00097        * \brief Make a new USRP source block.
00098        *
00099        * The USRP source block receives samples and writes to a stream.
00100        * The source block also provides API calls for receiver settings.
00101        *
00102        * RX Stream tagging:
00103        *
00104        * The following tag keys will be produced by the work function:
00105        *  - pmt::string_to_symbol("rx_time")
00106        *
00107        * The timstamp tag value is a pmt tuple of the following:
00108        * (uint64 seconds, and double fractional seconds).
00109        * A timestamp tag is produced at start() and after overflows.
00110        *
00111        * See the UHD manual for more detailed documentation:
00112        * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
00113        *
00114        * \param device_addr the address to identify the hardware
00115        * \param stream_args the IO format and channel specification
00116        * \return a new USRP source block object
00117        */
00118       static sptr make(const ::uhd::device_addr_t &device_addr,
00119                        const ::uhd::stream_args_t &stream_args);
00120 
00121       /*!
00122        * Set the start time for incoming samples.
00123        * To control when samples are received,
00124        * set this value before starting the flow graph.
00125        * The value is cleared after each run.
00126        * When not specified, the start time will be:
00127        *  - Immediately for the one channel case
00128        *  - in the near future for multi-channel
00129        *
00130        * \param time the absolute time for reception to begin
00131        */
00132       virtual void set_start_time(const ::uhd::time_spec_t &time) = 0;
00133 
00134       /*!
00135        * *Advanced use only:*
00136        * Issue a stream command to all channels in this source block.
00137        *
00138        * This method is intended to override the default "always on"
00139        * behavior. After starting the flow graph, the user should
00140        * call stop() on this block, then issue any desired arbitrary
00141        * stream_cmd_t structs to the device. The USRP will be able to
00142        * enqueue several stream commands in the FPGA.
00143        *
00144        * \param cmd the stream command to issue to all source channels
00145        */
00146       virtual void issue_stream_cmd(const ::uhd::stream_cmd_t &cmd) = 0;
00147 
00148       /*!
00149        * Returns identifying information about this USRP's configuration.
00150        * Returns motherboard ID, name, and serial.
00151        * Returns daughterboard RX ID, subdev name and spec, serial, and antenna.
00152        * \param chan channel index 0 to N-1
00153        * \return RX info
00154        */
00155       virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
00156 
00157       /*!
00158        * Set the frontend specification.
00159        * \param spec the subdev spec markup string
00160        * \param mboard the motherboard index 0 to M-1
00161        */
00162       virtual void set_subdev_spec(const std::string &spec, size_t mboard = 0) = 0;
00163 
00164       /*!
00165        * Get the RX frontend specification.
00166        * \param mboard the motherboard index 0 to M-1
00167        * \return the frontend specification in use
00168        */
00169       virtual std::string get_subdev_spec(size_t mboard = 0) = 0;
00170 
00171       /*!
00172        * Set the sample rate for the usrp device.
00173        * \param rate a new rate in Sps
00174        */
00175       virtual void set_samp_rate(double rate) = 0;
00176 
00177       /*!
00178        * Get the sample rate for the usrp device.
00179        * This is the actual sample rate and may differ from the rate set.
00180        * \return the actual rate in Sps
00181        */
00182       virtual double get_samp_rate(void) = 0;
00183 
00184       /*!
00185        * Get the possible sample rates for the usrp device.
00186        * \return a range of rates in Sps
00187        */
00188       virtual ::uhd::meta_range_t get_samp_rates(void) = 0;
00189 
00190       /*!
00191        * Tune the usrp device to the desired center frequency.
00192        * \param tune_request the tune request instructions
00193        * \param chan the channel index 0 to N-1
00194        * \return a tune result with the actual frequencies
00195        */
00196       virtual ::uhd::tune_result_t set_center_freq
00197         (const ::uhd::tune_request_t tune_request, size_t chan = 0) = 0;
00198 
00199       /*!
00200        * Tune the usrp device to the desired center frequency.
00201        * This is a wrapper around set center freq so that in this case,
00202        * the user can pass a single frequency in the call through swig.
00203        * \param freq the desired frequency in Hz
00204        * \param chan the channel index 0 to N-1
00205        * \return a tune result with the actual frequencies
00206        */
00207       ::uhd::tune_result_t set_center_freq(double freq, size_t chan = 0)
00208       {
00209         return set_center_freq(::uhd::tune_request_t(freq), chan);
00210       }
00211 
00212       /*!
00213        * Get the center frequency.
00214        * \param chan the channel index 0 to N-1
00215        * \return the frequency in Hz
00216        */
00217       virtual double get_center_freq(size_t chan = 0) = 0;
00218 
00219       /*!
00220        * Get the tunable frequency range.
00221        * \param chan the channel index 0 to N-1
00222        * \return the frequency range in Hz
00223        */
00224       virtual ::uhd::freq_range_t get_freq_range(size_t chan = 0) = 0;
00225 
00226       /*!
00227        * Set the gain for the dboard.
00228        * \param gain the gain in dB
00229        * \param chan the channel index 0 to N-1
00230        */
00231       virtual void set_gain(double gain, size_t chan = 0) = 0;
00232 
00233       /*!
00234        * Set the named gain on the dboard.
00235        * \param gain the gain in dB
00236        * \param name the name of the gain stage
00237        * \param chan the channel index 0 to N-1
00238        */
00239       virtual void set_gain(double gain,
00240                             const std::string &name,
00241                             size_t chan = 0) = 0;
00242 
00243       /*!
00244        * Get the actual dboard gain setting.
00245        * \param chan the channel index 0 to N-1
00246        * \return the actual gain in dB
00247        */
00248       virtual double get_gain(size_t chan = 0) = 0;
00249 
00250       /*!
00251        * Get the actual dboard gain setting of named stage.
00252        * \param name the name of the gain stage
00253        * \param chan the channel index 0 to N-1
00254        * \return the actual gain in dB
00255        */
00256       virtual double get_gain(const std::string &name,
00257                               size_t chan = 0) = 0;
00258 
00259       /*!
00260        * Get the actual dboard gain setting of named stage.
00261        * \param chan the channel index 0 to N-1
00262        * \return the actual gain in dB
00263        */
00264       virtual std::vector<std::string> get_gain_names(size_t chan = 0) = 0;
00265 
00266       /*!
00267        * Get the settable gain range.
00268        * \param chan the channel index 0 to N-1
00269        * \return the gain range in dB
00270        */
00271       virtual ::uhd::gain_range_t get_gain_range(size_t chan = 0) = 0;
00272 
00273       /*!
00274        * Get the settable gain range.
00275        * \param name the name of the gain stage
00276        * \param chan the channel index 0 to N-1
00277        * \return the gain range in dB
00278        */
00279       virtual ::uhd::gain_range_t get_gain_range(const std::string &name,
00280                                                size_t chan = 0) = 0;
00281 
00282       /*!
00283        * Set the antenna to use.
00284        * \param ant the antenna string
00285        * \param chan the channel index 0 to N-1
00286        */
00287       virtual void set_antenna(const std::string &ant,
00288                                size_t chan = 0) = 0;
00289 
00290       /*!
00291        * Get the antenna in use.
00292        * \param chan the channel index 0 to N-1
00293        * \return the antenna string
00294        */
00295       virtual std::string get_antenna(size_t chan = 0) = 0;
00296 
00297       /*!
00298        * Get a list of possible antennas.
00299        * \param chan the channel index 0 to N-1
00300        * \return a vector of antenna strings
00301        */
00302       virtual std::vector<std::string> get_antennas(size_t chan = 0) = 0;
00303 
00304       /*!
00305        * Set the bandpass filter on the RF frontend.
00306        * \param bandwidth the filter bandwidth in Hz
00307        * \param chan the channel index 0 to N-1
00308        */
00309       virtual void set_bandwidth(double bandwidth, size_t chan = 0) = 0;
00310 
00311       /*!
00312        * Get the bandpass filter setting on the RF frontend.
00313        * \param chan the channel index 0 to N-1
00314        * \return bandwidth of the filter in Hz
00315        */
00316       virtual double get_bandwidth(size_t chan = 0) = 0;
00317 
00318       /*!
00319        * Get the bandpass filter range of the RF frontend.
00320        * \param chan the channel index 0 to N-1
00321        * \return the range of the filter bandwidth in Hz
00322        */
00323       virtual ::uhd::freq_range_t get_bandwidth_range(size_t chan = 0) = 0;
00324 
00325       /*!
00326        * Enable/disable the automatic DC offset correction.
00327        * The automatic correction subtracts out the long-run average.
00328        *
00329        * When disabled, the averaging option operation is halted.
00330        * Once halted, the average value will be held constant until
00331        * the user re-enables the automatic correction or overrides the
00332        * value by manually setting the offset.
00333        *
00334        * \param enb true to enable automatic DC offset correction
00335        * \param chan the channel index 0 to N-1
00336        */
00337       virtual void set_auto_dc_offset(const bool enb, size_t chan = 0) = 0;
00338 
00339       /*!
00340        * Set a constant DC offset value.
00341        * The value is complex to control both I and Q.
00342        * Only set this when automatic correction is disabled.
00343        * \param offset the dc offset (1.0 is full-scale)
00344        * \param chan the channel index 0 to N-1
00345        */
00346       virtual void set_dc_offset(const std::complex<double> &offset, size_t chan = 0) = 0;
00347 
00348       /*!
00349        * Set the RX frontend IQ imbalance correction.
00350        * Use this to adjust the magnitude and phase of I and Q.
00351        *
00352        * \param correction the complex correction value
00353        * \param chan the channel index 0 to N-1
00354        */
00355       virtual void set_iq_balance(const std::complex<double> &correction,
00356                                   size_t chan = 0) = 0;
00357 
00358       /*!
00359        * Get a RF frontend sensor value.
00360        * \param name the name of the sensor
00361        * \param chan the channel index 0 to N-1
00362        * \return a sensor value object
00363        */
00364       virtual ::uhd::sensor_value_t get_sensor(const std::string &name,
00365                                                size_t chan = 0) = 0;
00366 
00367       /*!
00368        * Get a list of possible RF frontend sensor names.
00369        * \param chan the channel index 0 to N-1
00370        * \return a vector of sensor names
00371        */
00372       virtual std::vector<std::string> get_sensor_names(size_t chan = 0) = 0;
00373 
00374       //! DEPRECATED use get_sensor
00375       ::uhd::sensor_value_t get_dboard_sensor(const std::string &name,
00376                                             size_t chan = 0)
00377       {
00378         return this->get_sensor(name, chan);
00379       }
00380 
00381       //! DEPRECATED use get_sensor_names
00382       std::vector<std::string> get_dboard_sensor_names(size_t chan = 0)
00383       {
00384         return this->get_sensor_names(chan);
00385       }
00386 
00387       /*!
00388        * Get a motherboard sensor value.
00389        * \param name the name of the sensor
00390        * \param mboard the motherboard index 0 to M-1
00391        * \return a sensor value object
00392        */
00393       virtual ::uhd::sensor_value_t get_mboard_sensor(const std::string &name,
00394                                                       size_t mboard = 0) = 0;
00395 
00396       /*!
00397        * Get a list of possible motherboard sensor names.
00398        * \param mboard the motherboard index 0 to M-1
00399        * \return a vector of sensor names
00400        */
00401       virtual std::vector<std::string> get_mboard_sensor_names(size_t mboard = 0) = 0;
00402 
00403       /*!
00404        * Set the clock configuration.
00405        * DEPRECATED for set_time/clock_source.
00406        * \param clock_config the new configuration
00407        * \param mboard the motherboard index 0 to M-1
00408        */
00409       virtual void set_clock_config(const ::uhd::clock_config_t &clock_config,
00410                                     size_t mboard = 0) = 0;
00411 
00412       /*!
00413        * Set the time source for the usrp device.
00414        * This sets the method of time synchronization,
00415        * typically a pulse per second or an encoded time.
00416        * Typical options for source: external, MIMO.
00417        * \param source a string representing the time source
00418        * \param mboard which motherboard to set the config
00419        */
00420       virtual void set_time_source(const std::string &source,
00421                                    const size_t mboard = 0) = 0;
00422 
00423       /*!
00424        * Get the currently set time source.
00425        * \param mboard which motherboard to get the config
00426        * \return the string representing the time source
00427        */
00428       virtual std::string get_time_source(const size_t mboard) = 0;
00429 
00430       /*!
00431        * Get a list of possible time sources.
00432        * \param mboard which motherboard to get the list
00433        * \return a vector of strings for possible settings
00434        */
00435       virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0;
00436 
00437       /*!
00438        * Set the clock source for the usrp device.
00439        * This sets the source for a 10 Mhz reference clock.
00440        * Typical options for source: internal, external, MIMO.
00441        * \param source a string representing the clock source
00442        * \param mboard which motherboard to set the config
00443        */
00444       virtual void set_clock_source(const std::string &source,
00445                                     const size_t mboard = 0) = 0;
00446 
00447       /*!
00448        * Get the currently set clock source.
00449        * \param mboard which motherboard to get the config
00450        * \return the string representing the clock source
00451        */
00452       virtual std::string get_clock_source(const size_t mboard) = 0;
00453 
00454       /*!
00455        * Get a list of possible clock sources.
00456        * \param mboard which motherboard to get the list
00457        * \return a vector of strings for possible settings
00458        */
00459       virtual std::vector<std::string> get_clock_sources(const size_t mboard) = 0;
00460 
00461       /*!
00462        * Get the master clock rate.
00463        * \param mboard the motherboard index 0 to M-1
00464        * \return the clock rate in Hz
00465        */
00466       virtual double get_clock_rate(size_t mboard = 0) = 0;
00467 
00468       /*!
00469        * Set the master clock rate.
00470        * \param rate the new rate in Hz
00471        * \param mboard the motherboard index 0 to M-1
00472        */
00473       virtual void set_clock_rate(double rate, size_t mboard = 0) = 0;
00474 
00475       /*!
00476        * Get the current time registers.
00477        * \param mboard the motherboard index 0 to M-1
00478        * \return the current usrp time
00479        */
00480       virtual ::uhd::time_spec_t get_time_now(size_t mboard = 0) = 0;
00481 
00482       /*!
00483        * Get the time when the last pps pulse occured.
00484        * \param mboard the motherboard index 0 to M-1
00485        * \return the current usrp time
00486        */
00487       virtual ::uhd::time_spec_t get_time_last_pps(size_t mboard = 0) = 0;
00488 
00489       /*!
00490        * Sets the time registers immediately.
00491        * \param time_spec the new time
00492        * \param mboard the motherboard index 0 to M-1
00493        */
00494       virtual void set_time_now(const ::uhd::time_spec_t &time_spec,
00495                                 size_t mboard = 0) = 0;
00496 
00497       /*!
00498        * Set the time registers at the next pps.
00499        * \param time_spec the new time
00500        */
00501       virtual void set_time_next_pps(const ::uhd::time_spec_t &time_spec) = 0;
00502 
00503       /*!
00504        * Sync the time registers with an unknown pps edge.
00505        * \param time_spec the new time
00506        */
00507       virtual void set_time_unknown_pps(const ::uhd::time_spec_t &time_spec) = 0;
00508 
00509       /*!
00510        * Set the time at which the control commands will take effect.
00511        *
00512        * A timed command will back-pressure all subsequent timed
00513        * commands, assuming that the subsequent commands occur within
00514        * the time-window. If the time spec is late, the command will
00515        * be activated upon arrival.
00516        *
00517        * \param time_spec the time at which the next command will activate
00518        * \param mboard which motherboard to set the config
00519        */
00520       virtual void set_command_time(const ::uhd::time_spec_t &time_spec,
00521                                     size_t mboard = 0) = 0;
00522 
00523       /*!
00524        * Clear the command time so future commands are sent ASAP.
00525        *
00526        * \param mboard which motherboard to set the config
00527        */
00528       virtual void clear_command_time(size_t mboard = 0) = 0;
00529 
00530       /*!
00531        * Get access to the underlying uhd dboard iface object.
00532        * \return the dboard_iface object
00533        */
00534       virtual ::uhd::usrp::dboard_iface::sptr get_dboard_iface(size_t chan = 0) = 0;
00535 
00536       /*!
00537        * Get access to the underlying uhd device object.
00538        * \return the multi usrp device object
00539        */
00540       virtual ::uhd::usrp::multi_usrp::sptr get_device(void) = 0;
00541 
00542       /*!
00543        * Perform write on the user configuration register bus. These
00544        * only exist if the user has implemented custom setting
00545        * registers in the device FPGA.
00546        * \param addr 8-bit register address
00547        * \param data 32-bit register value
00548        * \param mboard which motherboard to set the user register
00549        */
00550       virtual void set_user_register(const uint8_t addr,
00551                                      const uint32_t data,
00552                                      size_t mboard = 0) = 0;
00553 
00554       /*!
00555        * Convenience function for finite data acquisition.
00556        * This is not to be used with the scheduler; rather,
00557        * one can request samples from the USRP in python.
00558        * //TODO assumes fc32
00559        * \param nsamps the number of samples
00560        * \return a vector of complex float samples
00561        */
00562       virtual std::vector<std::complex<float> >
00563         finite_acquisition(const size_t nsamps) = 0;
00564 
00565       /*!
00566        * Convenience function for finite data acquisition. This is the
00567        * multi-channel version of finite_acquisition; This is not to
00568        * be used with the scheduler; rather, one can request samples
00569        * from the USRP in python.
00570        * //TODO assumes fc32
00571        * \param nsamps the number of samples per channel
00572        * \return a vector of buffers, where each buffer represents a channel
00573        */
00574       virtual std::vector<std::vector<std::complex<float> > >
00575         finite_acquisition_v(const size_t nsamps) = 0;
00576     };
00577 
00578   } /* namespace uhd */
00579 } /* namespace gr */
00580 
00581 #endif /* INCLUDED_GR_UHD_USRP_SOURCE_H */