/*
 * Copyright 2020 Free Software Foundation, Inc.
 *
 * This file is part of GNU Radio
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 */
#include "pydoc_macros.h"
#define D(...) DOC(gr, digital, __VA_ARGS__)
/*
  This file contains placeholders for docstrings for the Python bindings.
  Do not edit! These were automatically extracted during the binding process
  and will be overwritten during the build process
 */


static const char* __doc_gr_digital_header_payload_demux = R"doc(Header/Payload demuxer (HPD).

This block is designed to demultiplex packets from a bursty transmission. The typical application for this block is the case when you are receiving packets with yet-to-determine length. This block will pass the header section to other blocks for demodulation. Using the information from the demodulated header, it will then output the payload. The beginning of the header needs to be identified by a trigger signal (see below).



Theory of OperationInput 0 takes a continuous transmission of samples (items). Input 1 is an optional input for the trigger signal (mark beginning of packets). In this case, a non-zero value on input 1 identifies the beginning of a packet. Otherwise, a tag with the key specified in  is used as a trigger (its value is irrelevant).


Until a trigger signal is detected, all samples are dropped onto the floor. Once a trigger is detected, a total of  items are copied to output 0. The block then stalls until it receives a message on the message port . The message must be a PMT dictionary; all key/value pairs are copied as tags to the first item of the payload (which is assumed to be the first item after the header). The value corresponding to the key specified in  is read and taken as the payload length. The payload, together with the header data as tags, is then copied to output 1.


If the header demodulation fails, the header must send a PMT with value pmt::PMT_F. The state gets reset and the header is ignored.




Symbols, Items and Item SizesTo generically and transparently handle different kinds of modulations, including OFDM, this block distinguishes between  and .


Items are what are consumed at the input. Anything that uses complex samples will therefore use an itemsize of . Symbols are a way of grouping items. In OFDM, we usually don't care about individual samples, but we do care about full OFDM symbols, so we set  to the IFFT / FFT length of the OFDM modulator / demodulator. For single-carrier modulations, this value can be set to the number of samples per symbol, to handle data in number of symbols, or to 1 to handle data in number of samples. If specified,  items are discarded before every symbol. This is useful for demuxing bursts of OFDM signals.


On the output, we can deal with symbols directly by setting  to true. In that case, the output item size is the .


 OFDM with 48 sub-carriers, using a length-64 IFFT on the modulator, and a cyclic-prefix length of 16 samples. In this case,  is , because we're receiving complex samples. One OFDM symbol has 64 samples, hence  is set to 64, and  to 16. The header length is specified in number of OFDM symbols. Because we want to deal with full OFDM symbols, we set  to true.


 PSK-modulated signals, with 4 samples per symbol. Again,  is  because we're still dealing with complex samples.  is 4, because one item is one sample.  must be set to 0. The header length is given in number of PSK symbols.




Handling timing uncertainty on the triggerBy default, the assumption is made that the trigger arrives on  the sample that the header starts. These triggers typically come from timing synchronization algorithms which may be suboptimal, and have a known timing uncertainty (e.g., we know the trigger might be a sample too early or too late).


The demuxer has an option for this case, the . If this value is non-zero, it specifies the number of items that are prepended and appended to the header before copying it to the header output.


Example: Say our synchronization algorithm can be off by up to two samples, and the header length is 20 samples. So we set  to 20, and  to 2. Now assume a trigger arrives on sample index 100. We copy a total of 24 samples to the header port, starting at sample index 98.


The payload is  padded. Let's say the header demod reports a payload length of 100. In the previous examples, we would copy 100 samples to the payload port, starting at sample index 120 (this means the padded samples appended to the header are copied to both ports!). However, the header demodulator has the option to specify a payload offset, which cannot exceed the padding value. To do this, include a key  in the message sent back to the HPD. A negative value means the payload starts earlier than otherwise. (If you wanted to always pad the payload, you could set  to  and increase the reported length of the payload).


Because the padding is specified in number of items, and not symbols, this value can only be multiples of the number of items per symbol  either  is true, or a guard interval is specified (or both). Note that in practice, it is rare that both a guard interval is specified  a padding value is required. The difference between the padding value and a guard interval is that a guard interval is part of the signal, and comes with  symbol, whereas the header padding is added to only the header, and is not by design.




Tag HandlingAny tags on the input stream are copied to the corresponding output  they're on an item that is propagated. Note that a tag on the header items is copied to the header stream; that means the header-parsing block must handle these tags if they should go on the payload. A special case are tags on items that make up the guard interval. These are copied to the first item of the following symbol. If a tag is situated very close to the end of the payload, it might be unclear if it belongs to this packet or the following. In this case, it is possible that the tag might be propagated twice.


Tags outside of packets are generally discarded. If there are tags that carry important information that must not be list, there are two additional mechanisms to preserve the tags:

Constructor Specific Documentation:



Args:
    header_len : Number of symbols per header
    items_per_symbol : Number of items per symbol
    guard_interval : Number of items between two consecutive symbols
    length_tag_key : Key of the frame length tag
    trigger_tag_key : Key of the trigger tag
    output_symbols : Output symbols (true) or items (false)?
    itemsize : Item size (bytes per item)
    timing_tag_key : The name of the tag with timing information, usually 'rx_time' or empty (this means timing info is discarded)
    samp_rate : Sampling rate at the input. Necessary to calculate the rx time of packets.
    special_tags : A vector of strings denoting tags which shall be preserved (see Tag Handling)
    header_padding : A number of items that is appended and prepended to the header.)doc";


static const char* __doc_gr_digital_header_payload_demux_header_payload_demux =
    R"doc()doc";


static const char* __doc_gr_digital_header_payload_demux_make = R"doc(Header/Payload demuxer (HPD).

This block is designed to demultiplex packets from a bursty transmission. The typical application for this block is the case when you are receiving packets with yet-to-determine length. This block will pass the header section to other blocks for demodulation. Using the information from the demodulated header, it will then output the payload. The beginning of the header needs to be identified by a trigger signal (see below).



Theory of OperationInput 0 takes a continuous transmission of samples (items). Input 1 is an optional input for the trigger signal (mark beginning of packets). In this case, a non-zero value on input 1 identifies the beginning of a packet. Otherwise, a tag with the key specified in  is used as a trigger (its value is irrelevant).


Until a trigger signal is detected, all samples are dropped onto the floor. Once a trigger is detected, a total of  items are copied to output 0. The block then stalls until it receives a message on the message port . The message must be a PMT dictionary; all key/value pairs are copied as tags to the first item of the payload (which is assumed to be the first item after the header). The value corresponding to the key specified in  is read and taken as the payload length. The payload, together with the header data as tags, is then copied to output 1.


If the header demodulation fails, the header must send a PMT with value pmt::PMT_F. The state gets reset and the header is ignored.




Symbols, Items and Item SizesTo generically and transparently handle different kinds of modulations, including OFDM, this block distinguishes between  and .


Items are what are consumed at the input. Anything that uses complex samples will therefore use an itemsize of . Symbols are a way of grouping items. In OFDM, we usually don't care about individual samples, but we do care about full OFDM symbols, so we set  to the IFFT / FFT length of the OFDM modulator / demodulator. For single-carrier modulations, this value can be set to the number of samples per symbol, to handle data in number of symbols, or to 1 to handle data in number of samples. If specified,  items are discarded before every symbol. This is useful for demuxing bursts of OFDM signals.


On the output, we can deal with symbols directly by setting  to true. In that case, the output item size is the .


 OFDM with 48 sub-carriers, using a length-64 IFFT on the modulator, and a cyclic-prefix length of 16 samples. In this case,  is , because we're receiving complex samples. One OFDM symbol has 64 samples, hence  is set to 64, and  to 16. The header length is specified in number of OFDM symbols. Because we want to deal with full OFDM symbols, we set  to true.


 PSK-modulated signals, with 4 samples per symbol. Again,  is  because we're still dealing with complex samples.  is 4, because one item is one sample.  must be set to 0. The header length is given in number of PSK symbols.




Handling timing uncertainty on the triggerBy default, the assumption is made that the trigger arrives on  the sample that the header starts. These triggers typically come from timing synchronization algorithms which may be suboptimal, and have a known timing uncertainty (e.g., we know the trigger might be a sample too early or too late).


The demuxer has an option for this case, the . If this value is non-zero, it specifies the number of items that are prepended and appended to the header before copying it to the header output.


Example: Say our synchronization algorithm can be off by up to two samples, and the header length is 20 samples. So we set  to 20, and  to 2. Now assume a trigger arrives on sample index 100. We copy a total of 24 samples to the header port, starting at sample index 98.


The payload is  padded. Let's say the header demod reports a payload length of 100. In the previous examples, we would copy 100 samples to the payload port, starting at sample index 120 (this means the padded samples appended to the header are copied to both ports!). However, the header demodulator has the option to specify a payload offset, which cannot exceed the padding value. To do this, include a key  in the message sent back to the HPD. A negative value means the payload starts earlier than otherwise. (If you wanted to always pad the payload, you could set  to  and increase the reported length of the payload).


Because the padding is specified in number of items, and not symbols, this value can only be multiples of the number of items per symbol  either  is true, or a guard interval is specified (or both). Note that in practice, it is rare that both a guard interval is specified  a padding value is required. The difference between the padding value and a guard interval is that a guard interval is part of the signal, and comes with  symbol, whereas the header padding is added to only the header, and is not by design.




Tag HandlingAny tags on the input stream are copied to the corresponding output  they're on an item that is propagated. Note that a tag on the header items is copied to the header stream; that means the header-parsing block must handle these tags if they should go on the payload. A special case are tags on items that make up the guard interval. These are copied to the first item of the following symbol. If a tag is situated very close to the end of the payload, it might be unclear if it belongs to this packet or the following. In this case, it is possible that the tag might be propagated twice.


Tags outside of packets are generally discarded. If there are tags that carry important information that must not be list, there are two additional mechanisms to preserve the tags:

Constructor Specific Documentation:



Args:
    header_len : Number of symbols per header
    items_per_symbol : Number of items per symbol
    guard_interval : Number of items between two consecutive symbols
    length_tag_key : Key of the frame length tag
    trigger_tag_key : Key of the trigger tag
    output_symbols : Output symbols (true) or items (false)?
    itemsize : Item size (bytes per item)
    timing_tag_key : The name of the tag with timing information, usually 'rx_time' or empty (this means timing info is discarded)
    samp_rate : Sampling rate at the input. Necessary to calculate the rx time of packets.
    special_tags : A vector of strings denoting tags which shall be preserved (see Tag Handling)
    header_padding : A number of items that is appended and prepended to the header.)doc";
