GNU Radio Manual and C++ API Reference 3.7.14.0
The Free & Open Software Radio Ecosystem
header_payload_demux.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/* Copyright 2012-2016 Free Software Foundation, Inc.
3 *
4 * This file is part of GNU Radio
5 *
6 * GNU Radio is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 3, or (at your option)
9 * any later version.
10 *
11 * GNU Radio is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with GNU Radio; see the file COPYING. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street,
19 * Boston, MA 02110-1301, USA.
20 */
21
22#ifndef INCLUDED_DIGITAL_HEADER_PAYLOAD_DEMUX_H
23#define INCLUDED_DIGITAL_HEADER_PAYLOAD_DEMUX_H
24
25#include <gnuradio/block.h>
27
28namespace gr {
29namespace digital {
30
31/*!
32 * \brief Header/Payload demuxer (HPD).
33 * \ingroup packet_operators_blk
34 *
35 * \details
36 * This block is designed to demultiplex packets from a bursty transmission.
37 * The typical application for this block is the case when you are receiving
38 * packets with yet-to-determine length. This block will pass the header
39 * section to other blocks for demodulation. Using the information from the
40 * demodulated header, it will then output the payload. The beginning of the
41 * header needs to be identified by a trigger signal (see below).
42 *
43 * \section hpd_theory_of_ops Theory of Operation
44 *
45 * Input 0 takes a continuous transmission of samples (items).
46 * Input 1 is an optional input for the trigger signal (mark beginning of
47 * packets). In this case, a non-zero value on input 1 identifies the beginning of a
48 * packet. Otherwise, a tag with the key specified in \p trigger_tag_key is used as a
49 * trigger (its value is irrelevant).
50 *
51 * Until a trigger signal is detected, all samples are dropped onto the floor.
52 * Once a trigger is detected, a total of \p header_len items are copied to output 0.
53 * The block then stalls until it receives a message on the message port
54 * \p header_data. The message must be a PMT dictionary; all key/value pairs are
55 * copied as tags to the first item of the payload (which is assumed to be the
56 * first item after the header).
57 * The value corresponding to the key specified in \p length_tag_key is read
58 * and taken as the payload length. The payload, together with the header data
59 * as tags, is then copied to output 1.
60 *
61 * If the header demodulation fails, the header must send a PMT with value
62 * pmt::PMT_F. The state gets reset and the header is ignored.
63 *
64 * \section hpd_item_sizes Symbols, Items and Item Sizes
65 *
66 * To generically and transparently handle different kinds of modulations,
67 * including OFDM, this block distinguises between \b symbols and \b items.
68 *
69 * Items are what are consumed at the input. Anything that uses complex samples
70 * will therefore use an itemsize of `sizeof(gr_complex)`. Symbols are a way of
71 * grouping items. In OFDM, we usually don't care about individual samples, but
72 * we do care about full OFDM symbols, so we set \p items_per_symbol to the
73 * IFFT / FFT length of the OFDM modulator / demodulator.
74 * For single-carrier modulations, this value can be set to the number of
75 * samples per symbol, to handle data in number of symbols, or to 1 to
76 * handle data in number of samples.
77 * If specified, \p guard_interval items are discarded before every symbol.
78 * This is useful for demuxing bursts of OFDM signals.
79 *
80 * On the output, we can deal with symbols directly by setting \p output_symbols
81 * to true. In that case, the output item size is the <em>symbol size</em>.
82 *
83 * \b Example: OFDM with 48 sub-carriers, using a length-64 IFFT on the
84 * modulator, and a cyclic-prefix length of 16 samples. In this case,
85 * \p itemsize is `sizeof(gr_complex)`, because we're receiving complex
86 * samples. One OFDM symbol has 64 samples, hence \p items_per_symbol is
87 * set to 64, and \p guard_interval to 16. The header length is specified
88 * in number of OFDM symbols. Because we want to deal with full OFDM
89 * symbols, we set \p output_symbols to true.
90 *
91 * \b Example: PSK-modulated signals, with 4 samples per symbol. Again,
92 * \p itemsize is `sizeof(gr_complex)` because we're still dealing with
93 * complex samples. \p items_per_symbol is 4, because one item is one
94 * sample. \p guard_interval must be set to 0. The header length is
95 * given in number of PSK symbols.
96 *
97 * \section hpd_uncertainty Handling timing uncertainty on the trigger
98 *
99 * By default, the assumption is made that the trigger arrives on *exactly*
100 * the sample that the header starts. These triggers typically come from
101 * timing synchronization algorithms which may be suboptimal, and have a
102 * known timing uncertainty (e.g., we know the trigger might be a sample
103 * too early or too late).
104 *
105 * The demuxer has an option for this case, the \p header_padding. If this
106 * value is non-zero, it specifies the number of items that are prepended
107 * and appended to the header before copying it to the header output.
108 *
109 * Example: Say our synchronization algorithm can be off by up to two
110 * samples, and the header length is 20 samples. So we set \p header_len
111 * to 20, and \p header_padding to 2.
112 * Now assume a trigger arrives on sample index 100. We copy a total of
113 * 24 samples to the header port, starting at sample index 98.
114 *
115 * The payload is *not* padded. Let's say the header demod reports a
116 * payload length of 100. In the previous examples, we would copy 100
117 * samples to the payload port, starting at sample index 120 (this means
118 * the padded samples appended to the header are copied to both ports!).
119 * However, the header demodulator has the option to specify a payload
120 * offset, which cannot exceed the padding value. To do this, include
121 * a key `payload_offset` in the message sent back to the HPD. A negative
122 * value means the payload starts earlier than otherwise.
123 * (If you wanted to always pad the payload, you could set `payload_offset`
124 * to `-header_padding` and increase the reported length of the payload).
125 *
126 * Because the padding is specified in number of items, and not symbols,
127 * this value can only be multiples of the number of items per symbol *if*
128 * either \p output_symbols is true, or a guard interval is specified (or
129 * both). Note that in practice, it is rare that both a guard interval is
130 * specified *and* a padding value is required. The difference between the
131 * padding value and a guard interval is that a guard interval is part of
132 * the signal, and comes with *every* symbol, whereas the header padding
133 * is added to only the header, and is not by design.
134 *
135 * \section hpd_tag_handling Tag Handling
136 *
137 * Any tags on the input stream are copied to the corresponding output *if* they're
138 * on an item that is propagated. Note that a tag on the header items is copied to the
139 * header stream; that means the header-parsing block must handle these tags if they
140 * should go on the payload.
141 * A special case are tags on items that make up the guard interval. These are copied
142 * to the first item of the following symbol.
143 * If a tag is situated very close to the end of the payload, it might be unclear if
144 * it belongs to this packet or the following. In this case, it is possible that the
145 * tag might be propagated twice.
146 *
147 * Tags outside of packets are generally discarded. If there are tags that
148 * carry important information that must not be list, there are two
149 * additional mechanisms to preserve the tags:
150 * - Timing tags might be relevant to know \b when a packet was received. By
151 * specifying the name of a timestamp tag and the sample rate at this block, it
152 * keeps track of the time and will add the time to the first item of every packet.
153 * The name of the timestamp tag is usually 'rx_time' (see, e.g.,
154 * gr::uhd::usrp_source::make()).
155 * The time value must be specified in the UHD time format.
156 * - Other tags are simply stored and updated. As an example, the user might want to know
157 * the rx frequency, which UHD stores in the rx_freq tag. In this case, add the tag name
158 * 'rx_freq' to the list of \p special_tags. This block will then always save the most
159 * current value of 'rx_freq' and add it to the beginning of every packet.
160 *
161 */
163{
164public:
165 typedef boost::shared_ptr<header_payload_demux> sptr;
166
167 /*!
168 * \param header_len Number of symbols per header
169 * \param items_per_symbol Number of items per symbol
170 * \param guard_interval Number of items between two consecutive symbols
171 * \param length_tag_key Key of the frame length tag
172 * \param trigger_tag_key Key of the trigger tag
173 * \param output_symbols Output symbols (true) or items (false)?
174 * \param itemsize Item size (bytes per item)
175 * \param timing_tag_key The name of the tag with timing information, usually
176 * 'rx_time' or empty (this means timing info is discarded) \param samp_rate Sampling
177 * rate at the input. Necessary to calculate the rx time of packets. \param
178 * special_tags A vector of strings denoting tags which shall be preserved (see \ref
179 * hpd_tag_handling) \param header_padding A number of items that is appended and
180 * prepended to the header.
181 */
182 static sptr
183 make(const int header_len,
184 const int items_per_symbol = 1,
185 const int guard_interval = 0,
186 const std::string& length_tag_key = "frame_len",
187 const std::string& trigger_tag_key = "",
188 const bool output_symbols = false,
189 const size_t itemsize = sizeof(gr_complex),
190 const std::string& timing_tag_key = "",
191 const double samp_rate = 1.0,
192 const std::vector<std::string>& special_tags = std::vector<std::string>(),
193 const size_t header_padding = 0);
194};
195
196} // namespace digital
197} // namespace gr
198
199#endif /* INCLUDED_DIGITAL_HEADER_PAYLOAD_DEMUX_H */
The abstract base class for all 'terminal' processing blocks.
Definition: block.h:66
Header/Payload demuxer (HPD).
Definition: header_payload_demux.h:163
static sptr make(const int header_len, const int items_per_symbol=1, const int guard_interval=0, const std::string &length_tag_key="frame_len", const std::string &trigger_tag_key="", const bool output_symbols=false, const size_t itemsize=sizeof(gr_complex), const std::string &timing_tag_key="", const double samp_rate=1.0, const std::vector< std::string > &special_tags=std::vector< std::string >(), const size_t header_padding=0)
boost::shared_ptr< header_payload_demux > sptr
Definition: header_payload_demux.h:165
#define DIGITAL_API
Definition: gr-digital/include/gnuradio/digital/api.h:30
std::complex< float > gr_complex
Definition: gr_complex.h:27
BLOCKS_API size_t itemsize(vector_type type)
Include this header to use the message passing features.
Definition: basic_block.h:45