GNU Radio 3.7.3 C++ API
header_payload_demux.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /* Copyright 2012 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/digital/api.h>
26 #include <gnuradio/block.h>
27 
28 namespace gr {
29  namespace digital {
30 
31  /*!
32  * \brief Header/Payload demuxer.
33  * \ingroup packet_operators_blk
34  *
35  * \details
36  * This block is designed to handle packets from a bursty transmission.
37  * Input 0 takes a continuous transmission of samples.
38  * If used, input 1 is a trigger signal. In this case, a 1 on input 1
39  * is a trigger. Otherwise, a tag with the key specified in \p trigger_tag_key
40  * is used as a trigger (its value is irrelevant).
41  *
42  * Until a trigger signal is detected, all samples are dropped onto the floor.
43  * Once a trigger is detected, a total of \p header_len items are copied to output 0.
44  * The block then stalls until it receives a message on the message port
45  * \p header_data. The message must be a PMT dictionary; all key/value pairs are
46  * copied as tags to the first item of the payload (which is assumed to be the
47  * first item after the header).
48  * The value corresponding to the key specified in \p length_tag_key is read
49  * and taken as the payload length. The payload, together with the header data
50  * as tags, is then copied to output 1.
51  *
52  * If specified, \p guard_interval items are discarded before every symbol.
53  * This is useful for demuxing bursts of OFDM signals.
54  *
55  * Any tags on the input stream are copied to the corresponding output *if* they're
56  * on an item that is propagated. Note that a tag on the header items is copied to the
57  * header stream; that means the header-parsing block must handle these tags if they
58  * should go on the payload.
59  * A special case are tags on items that make up the guard interval. These are copied
60  * to the first item of the following symbol.
61  * If a tag is situated very close to the end of the payload, it might be unclear if
62  * it belongs to this packet or the following. In this case, the tag might be propagated
63  * twice.
64  *
65  * Tags outside of packets are generally discarded. If this information is important,
66  * there are two additional mechanisms to preserve the tags:
67  * - Timing tags might be relevant to know <em>when</em> a packet was received. By
68  * specifying the name of a timestamp tag and the sample rate at this block, it
69  * keeps track of the time and will add the time to the first item of every packet.
70  * The name of the timestamp tag is usually 'rx_time' (see gr::uhd::usrp_source::make()).
71  * The time value must be specified in the UHD time format.
72  * - Other tags are simply stored and updated. As an example, the user might want to know the
73  * rx frequency, which UHD stores in the rx_freq tag. In this case, add the tag name 'rx_freq'
74  * to the list of \p special_tags. This block will then always save the most current value of
75  * 'rx_freq' and add it to the beginning of every packet.
76  *
77  */
78  class DIGITAL_API header_payload_demux : virtual public block
79  {
80  public:
82 
83  /*!
84  * \param header_len Number of symbols per header
85  * \param items_per_symbol Number of items per symbol
86  * \param guard_interval Number of items between two consecutive symbols
87  * \param length_tag_key Key of the frame length tag
88  * \param trigger_tag_key Key of the trigger tag
89  * \param output_symbols Output symbols (true) or items (false)?
90  * \param itemsize Item size (bytes per item)
91  * \param timing_tag_key The name of the tag with timing information, usually 'rx_time' or empty (this means timing info is discarded)
92  * \param samp_rate Sampling rate at the input. Necessary to calculate the rx time of packets.
93  * \param special_tags A vector of strings denoting tags which shall be preserved.
94  */
95  static sptr make(
96  int header_len,
97  int items_per_symbol,
98  int guard_interval=0,
99  const std::string &length_tag_key="frame_len",
100  const std::string &trigger_tag_key="",
101  bool output_symbols=false,
102  size_t itemsize=sizeof(gr_complex),
103  const std::string &timing_tag_key="",
104  const double samp_rate=1.0,
105  const std::vector<std::string> &special_tags=std::vector<std::string>()
106  );
107  };
108 
109  } // namespace digital
110 } // namespace gr
111 
112 #endif /* INCLUDED_DIGITAL_HEADER_PAYLOAD_DEMUX_H */
113 
#define DIGITAL_API
Definition: gr-digital/include/gnuradio/digital/api.h:30
shared_ptr documentation stub
Definition: shared_ptr_docstub.h:15
std::complex< float > gr_complex
Definition: gr_complex.h:27
Header/Payload demuxer.
Definition: header_payload_demux.h:78
The abstract base class for all 'terminal' processing blocks.A signal processing flow is constructed ...
Definition: block.h:60
boost::shared_ptr< header_payload_demux > sptr
Definition: header_payload_demux.h:81
BLOCKS_API size_t itemsize(vector_type type)