GNU Radio Manual and C++ API Reference 3.7.14.0
The Free & Open Software Radio Ecosystem
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
27
28// TODO In 3.8, UHD 3.4 will be required and we can remove all these ifdefs
29#ifndef INCLUDED_UHD_STREAM_HPP
30namespace uhd {
32 stream_args_t(const std::string& cpu = "", const std::string& otw = "")
33 {
34 cpu_format = cpu;
35 otw_format = otw;
36 }
37 std::string cpu_format;
38 std::string otw_format;
39 device_addr_t args;
40 std::vector<size_t> channels;
41};
42} // namespace uhd
43#define INCLUDED_UHD_STREAM_HPP
44#else
45#define GR_UHD_USE_STREAM_API
46#endif
47
48namespace gr {
49namespace uhd {
50
51class uhd_usrp_sink;
52
53/*! USRP Sink -- Radio Transmitter
54 * \ingroup uhd_blk
55 *
56 *
57 * The USRP sink block reads a stream and transmits the samples.
58 * The sink block also provides API calls for transmitter settings.
59 * See also gr::uhd::usrp_block for more public API calls.
60 *
61 * \section uhd_tx_tagging TX Stream tagging
62 *
63 * The following tag keys will be consumed by the work function:
64 * - pmt::string_to_symbol("tx_sob")
65 * - pmt::string_to_symbol("tx_eob")
66 * - pmt::string_to_symbol("tx_time")
67 * - pmt::string_to_symbol("tx_freq")
68 * - pmt::string_to_symbol("tx_command")
69 * - pmt::string_to_symbol(tsb_tag_name)
70 *
71 * Any other tag will be ignored.
72 *
73 * \section uhd_tx_burstys Bursty Transmission
74 *
75 * There are multiple ways to do bursty transmission without triggering
76 * underruns:
77 * - Using SOB/EOB tags
78 * - Using tagged streams (See \ref page_tagged_stream_blocks)
79 *
80 * The sob and eob (start and end of burst) tag values are pmt booleans.
81 * When present, burst tags should be set to true (pmt::PMT_T).
82 *
83 * If `tsb_tag_name` is not an empty string, all "tx_sob" and "tx_eob"
84 * tags will be ignored, and the input is assumed to a tagged stream.
85 *
86 * If sob/eob tags or length tags are used, this block understands that
87 * the data is bursty, and will configure the USRP to make sure there's
88 * no underruns after transmitting the final sample of a burst.
89 *
90 * \section uhd_tx_time Timestamps
91 *
92 * The timestamp tag value is a PMT tuple of the following:
93 * (uint64 seconds, double fractional seconds).
94 *
95 * The tx_freq tag has to be a double or a pair of form (channel, frequency),
96 * with frequency being a double and channel being an integer.
97 * This tag will trigger a tune command to the USRP
98 * to the given frequency, if possible. Note that oscillators need some time
99 * to stabilize after this! Don't expect clean data to be sent immediately after this
100 * command. If channel is omitted, and only a double is given, it will set this frequency
101 * to all channels.
102 *
103 * The command tag can carry a PMT command. See the following section.
104 *
105 * \section uhd_tx_commands Command interface
106 *
107 * There are two ways of passing commands to this block:
108 * 1. tx_command tag. The command is attached to a sample, and will executed
109 * before the sample is transmitted, and after the previous sample.
110 * 2. The 'command' message port. The command is executed asynchronously,
111 * as soon as possible.
112 *
113 * In both cases, the payload of the command is a PMT command, as described
114 * in Section \ref uhd_command_syntax.
115 *
116 * For a more general description of the gr-uhd components, see \ref page_uhd.
117 */
118class GR_UHD_API usrp_sink : virtual public usrp_block
119{
120public:
121 // gr::uhd::usrp_sink::sptr
122 typedef boost::shared_ptr<usrp_sink> sptr;
123
124 /*!
125 * \brief DEPRECATED Make a new USRP sink block using the deprecated io_type_t.
126 * \ingroup uhd_blk
127 *
128 * This function will be removed in the future. Please use the other make function,
129 * gr::uhd::usrp_sink::make(const ::uhd::device_addr_t, const ::uhd::stream_args_t,
130 * const std::string).
131 */
132 static sptr make(const ::uhd::device_addr_t& device_addr,
133 const ::uhd::io_type_t& io_type,
134 size_t num_channels);
135
136 /*!
137 * \param device_addr the address to identify the hardware
138 * \param stream_args the IO format and channel specification
139 * \param tsb_tag_name the name of the tag identifying tagged stream length
140 * \return a new USRP sink block object
141 */
142 static sptr make(const ::uhd::device_addr_t& device_addr,
143 const ::uhd::stream_args_t& stream_args,
144 const std::string& tsb_tag_name = "");
145
146 /*!
147 * Set the start time for outgoing samples.
148 * To control when samples are transmitted,
149 * set this value before starting the flow graph.
150 * The value is cleared after each run.
151 * When not specified, the start time will be:
152 * - Immediately for the one channel case
153 * - in the near future for multi-channel
154 *
155 * \param time the absolute time for transmission to begin
156 */
157 virtual void set_start_time(const ::uhd::time_spec_t& time) = 0;
158
159 /*!
160 * Returns identifying information about this USRP's configuration.
161 * Returns motherboard ID, name, and serial.
162 * Returns daughterboard TX ID, subdev name and spec, serial, and antenna.
163 * \param chan channel index 0 to N-1
164 * \return TX info
165 */
166 virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
167
168 /*!
169 * Set a constant DC offset value.
170 * The value is complex to control both I and Q.
171 * \param offset the dc offset (1.0 is full-scale)
172 * \param chan the channel index 0 to N-1
173 */
174 virtual void set_dc_offset(const std::complex<double>& offset, size_t chan = 0) = 0;
175
176 /*!
177 * Set the RX frontend IQ imbalance correction.
178 * Use this to adjust the magnitude and phase of I and Q.
179 *
180 * \param correction the complex correction (1.0 is full-scale)
181 * \param chan the channel index 0 to N-1
182 */
183 virtual void set_iq_balance(const std::complex<double>& correction,
184 size_t chan = 0) = 0;
185};
186
187} /* namespace uhd */
188} /* namespace gr */
189
190#endif /* INCLUDED_GR_UHD_USRP_SINK_H */
Definition: usrp_block.h:65
Definition: usrp_sink.h:119
virtual void set_start_time(const ::uhd::time_spec_t &time)=0
virtual ::uhd::dict< std::string, std::string > get_usrp_info(size_t chan=0)=0
virtual void set_iq_balance(const std::complex< double > &correction, size_t chan=0)=0
boost::shared_ptr< usrp_sink > sptr
Definition: usrp_sink.h:122
virtual void set_dc_offset(const std::complex< double > &offset, 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
static sptr make(const ::uhd::device_addr_t &device_addr, const ::uhd::io_type_t &io_type, size_t num_channels)
DEPRECATED Make a new USRP sink block using the deprecated io_type_t.
Include this header to use the message passing features.
Definition: basic_block.h:45
Definition: usrp_sink.h:30
Definition: usrp_sink.h:31
std::string otw_format
Definition: usrp_sink.h:38
device_addr_t args
Definition: usrp_sink.h:39
std::string cpu_format
Definition: usrp_sink.h:37
std::vector< size_t > channels
Definition: usrp_sink.h:40
stream_args_t(const std::string &cpu="", const std::string &otw="")
Definition: usrp_sink.h:32