GNU Radio Manual and C++ API Reference 3.8.5.0
The Free & Open Software Radio Ecosystem
 
Loading...
Searching...
No Matches
usrp_sink.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/*
3 * Copyright 2010-2016 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
27
28namespace gr {
29namespace uhd {
30
31class uhd_usrp_sink;
32
33/*! USRP Sink -- Radio Transmitter
34 * \ingroup uhd_blk
35 *
36 *
37 * The USRP sink block reads a stream and transmits the samples.
38 * The sink block also provides API calls for transmitter settings.
39 * See also gr::uhd::usrp_block for more public API calls.
40 *
41 * \section uhd_tx_tagging TX Stream tagging
42 *
43 * The following tag keys will be consumed by the work function:
44 * - pmt::string_to_symbol("tx_sob")
45 * - pmt::string_to_symbol("tx_eob")
46 * - pmt::string_to_symbol("tx_time")
47 * - pmt::string_to_symbol("tx_freq")
48 * - pmt::string_to_symbol("tx_command")
49 * - pmt::string_to_symbol(tsb_tag_name)
50 *
51 * Any other tag will be ignored.
52 *
53 * \section uhd_tx_burstys Bursty Transmission
54 *
55 * There are multiple ways to do bursty transmission without triggering
56 * underruns:
57 * - Using SOB/EOB tags
58 * - Using tagged streams (See <a
59 * href="https://wiki.gnuradio.org/index.php/Tagged_Stream_Blocks" target="_blank">Tagged
60 * Stream Blocks</a>)
61 *
62 * The sob and eob (start and end of burst) tag values are pmt booleans.
63 * When present, burst tags should be set to true (pmt::PMT_T).
64 *
65 * If `tsb_tag_name` is not an empty string, all "tx_sob" and "tx_eob"
66 * tags will be ignored, and the input is assumed to a tagged stream.
67 *
68 * If sob/eob tags or length tags are used, this block understands that
69 * the data is bursty, and will configure the USRP to make sure there's
70 * no underruns after transmitting the final sample of a burst.
71 *
72 * \section uhd_tx_time Timestamps
73 *
74 * The timestamp tag value is a PMT tuple of the following:
75 * (uint64 seconds, double fractional seconds).
76 *
77 * The tx_freq tag has to be a double or a pair of form (channel, frequency),
78 * with frequency being a double and channel being an integer.
79 * This tag will trigger a tune command to the USRP
80 * to the given frequency, if possible. Note that oscillators need some time
81 * to stabilize after this! Don't expect clean data to be sent immediately after this
82 * command. If channel is omitted, and only a double is given, it will set this frequency
83 * to all channels.
84 *
85 * The command tag can carry a PMT command. See the following section.
86 *
87 * \section uhd_tx_commands Command interface
88 *
89 * There are two ways of passing commands to this block:
90 * 1. tx_command tag. The command is attached to a sample, and will executed
91 * before the sample is transmitted, and after the previous sample.
92 * 2. The 'command' message port. The command is executed asynchronously,
93 * as soon as possible.
94 *
95 * In both cases, the payload of the command is a PMT command, as described
96 * in Section \ref uhd_command_syntax.
97 *
98 * For a more general description of the gr-uhd components, see \ref page_uhd.
99 */
100class GR_UHD_API usrp_sink : virtual public usrp_block
101{
102public:
103 // gr::uhd::usrp_sink::sptr
104 typedef boost::shared_ptr<usrp_sink> sptr;
105
106 /*!
107 * \param device_addr the address to identify the hardware
108 * \param stream_args the IO format and channel specification
109 * \param tsb_tag_name the name of the tag identifying tagged stream length
110 * \return a new USRP sink block object
111 */
112 static sptr make(const ::uhd::device_addr_t& device_addr,
113 const ::uhd::stream_args_t& stream_args,
114 const std::string& tsb_tag_name = "");
115
116 /*!
117 * Set the start time for outgoing samples.
118 * To control when samples are transmitted,
119 * set this value before starting the flow graph.
120 * The value is cleared after each run.
121 * When not specified, the start time will be:
122 * - Immediately for the one channel case
123 * - in the near future for multi-channel
124 *
125 * \param time the absolute time for transmission to begin
126 */
127 virtual void set_start_time(const ::uhd::time_spec_t& time) = 0;
128
129 /*!
130 * Returns identifying information about this USRP's configuration.
131 * Returns motherboard ID, name, and serial.
132 * Returns daughterboard TX ID, subdev name and spec, serial, and antenna.
133 * \param chan channel index 0 to N-1
134 * \return TX info
135 */
136 virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
137
138 /*!
139 * Get a list of possible LO stage names
140 * \param chan the channel index 0 to N-1
141 * \return a vector of strings for possible LO names
142 */
143 virtual std::vector<std::string> get_lo_names(size_t chan = 0) = 0;
144
145 /*!
146 * Set the LO source for the usrp device.
147 * For usrps that support selectable LOs, this function
148 * allows switching between them.
149 * Typical options for source: internal, external.
150 * \param src a string representing the LO source
151 * \param name the name of the LO stage to update
152 * \param chan the channel index 0 to N-1
153 */
154 virtual void
155 set_lo_source(const std::string& src, const std::string& name, size_t chan = 0) = 0;
156
157 /*!
158 * Get the currently set LO source.
159 * \param name the name of the LO stage to query
160 * \param chan the channel index 0 to N-1
161 * \return the configured LO source
162 */
163 virtual const std::string get_lo_source(const std::string& name, size_t chan = 0) = 0;
164
165 /*!
166 * Get a list of possible LO sources.
167 * \param name the name of the LO stage to query
168 * \param chan the channel index 0 to N-1
169 * \return a vector of strings for possible settings
170 */
171 virtual std::vector<std::string> get_lo_sources(const std::string& name,
172 size_t chan = 0) = 0;
173
174 /*!
175 * Set whether the LO used by the usrp device is exported
176 * For usrps that support exportable LOs, this function
177 * configures if the LO used by chan is exported or not.
178 * \param enabled if true then export the LO
179 * \param name the name of the LO stage to update
180 * \param chan the channel index 0 to N-1 for the source channel
181 */
182 virtual void
183 set_lo_export_enabled(bool enabled, const std::string& name, size_t chan = 0) = 0;
184
185 /*!
186 * Returns true if the currently selected LO is being exported.
187 * \param name the name of the LO stage to query
188 * \param chan the channel index 0 to N-1
189 */
190 virtual bool get_lo_export_enabled(const std::string& name, size_t chan = 0) = 0;
191
192 /*!
193 * Set the RX LO frequency (Advanced).
194 * \param freq the frequency to set the LO to
195 * \param name the name of the LO stage to update
196 * \param chan the channel index 0 to N-1
197 * \return a coerced LO frequency
198 */
199 virtual double set_lo_freq(double freq, const std::string& name, size_t chan = 0) = 0;
200
201 /*!
202 * Get the current RX LO frequency (Advanced).
203 * \param name the name of the LO stage to query
204 * \param chan the channel index 0 to N-1
205 * \return the configured LO frequency
206 */
207 virtual double get_lo_freq(const std::string& name, size_t chan = 0) = 0;
208
209 /*!
210 * Get the LO frequency range of the RX LO.
211 * \param name the name of the LO stage to query
212 * \param chan the channel index 0 to N-1
213 * \return a frequency range object
214 */
215 virtual ::uhd::freq_range_t get_lo_freq_range(const std::string& name,
216 size_t chan = 0) = 0;
217
218 /*!
219 * Set a constant DC offset value.
220 * The value is complex to control both I and Q.
221 * \param offset the dc offset (1.0 is full-scale)
222 * \param chan the channel index 0 to N-1
223 */
224 virtual void set_dc_offset(const std::complex<double>& offset, size_t chan = 0) = 0;
225
226 /*!
227 * Set the RX frontend IQ imbalance correction.
228 * Use this to adjust the magnitude and phase of I and Q.
229 *
230 * \param correction the complex correction (1.0 is full-scale)
231 * \param chan the channel index 0 to N-1
232 */
233 virtual void set_iq_balance(const std::complex<double>& correction,
234 size_t chan = 0) = 0;
235};
236
237} /* namespace uhd */
238} /* namespace gr */
239
240#endif /* INCLUDED_GR_UHD_USRP_SINK_H */
Definition usrp_block.h:61
Definition usrp_sink.h:101
virtual void set_lo_source(const std::string &src, const std::string &name, size_t chan=0)=0
virtual void set_lo_export_enabled(bool enabled, const std::string &name, size_t chan=0)=0
virtual void set_start_time(const ::uhd::time_spec_t &time)=0
virtual ::uhd::freq_range_t get_lo_freq_range(const std::string &name, size_t chan=0)=0
virtual bool get_lo_export_enabled(const std::string &name, size_t chan=0)=0
virtual std::vector< std::string > get_lo_names(size_t chan=0)=0
virtual ::uhd::dict< std::string, std::string > get_usrp_info(size_t chan=0)=0
virtual double set_lo_freq(double freq, const std::string &name, size_t chan=0)=0
virtual std::vector< std::string > get_lo_sources(const std::string &name, size_t chan=0)=0
virtual void set_iq_balance(const std::complex< double > &correction, size_t chan=0)=0
virtual const std::string get_lo_source(const std::string &name, size_t chan=0)=0
boost::shared_ptr< usrp_sink > sptr
Definition usrp_sink.h:104
virtual void set_dc_offset(const std::complex< double > &offset, size_t chan=0)=0
virtual double get_lo_freq(const std::string &name, size_t chan=0)=0
static sptr make(const ::uhd::device_addr_t &device_addr, const ::uhd::stream_args_t &stream_args, const std::string &tsb_tag_name="")
#define GR_UHD_API
Definition gr-uhd/include/gnuradio/uhd/api.h:30
GNU Radio logging wrapper for log4cpp library (C++ port of log4j)
Definition basic_block.h:46