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