gr::digital::header_payload_demux
gr::block
gnuradio/digital/header_payload_demux.h
std::shared_ptr< header_payload_demux > typedef std::shared_ptr<header_payload_demux> gr::digital::header_payload_demux::sptr sptr gr::digital::header_payload_demux::sptr
sptr static sptr gr::digital::header_payload_demux::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) make gr::digital::header_payload_demux::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

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.

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 Operation

Input 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 `trigger_tag_key` 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 `header_len` items are copied to output 0. The block then stalls until it receives a message on the message port `header_data`. 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 `length_tag_key` 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 Sizes

To generically and transparently handle different kinds of modulations, including OFDM, this block distinguishes between symbols and items.

Items are what are consumed at the input. Anything that uses complex samples will therefore use an itemsize of `sizeof(gr_complex)`. 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 `items_per_symbol` 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, `guard_interval` 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 `output_symbols` to true. In that case, the output item size is the symbol size.

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

Example: PSK-modulated signals, with 4 samples per symbol. Again, `itemsize` is `sizeof(gr_complex)` because we're still dealing with complex samples. `items_per_symbol` is 4, because one item is one sample. `guard_interval` must be set to 0. The header length is given in number of PSK symbols.

# Handling timing uncertainty on the trigger

By default, the assumption is made that the trigger arrives on exactly 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 `header_padding`. 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 `header_len` to 20, and `header_padding` 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 not 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 `payload_offset` 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 `payload_offset` to `-header_padding` 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 if either `output_symbols` is true, or a guard interval is specified (or both). Note that in practice, it is rare that both a guard interval is specified and 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 every symbol, whereas the header padding is added to only the header, and is not by design.

# Tag Handling

Any tags on the input stream are copied to the corresponding output if 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:

- Timing tags might be relevant to know when a packet was received. By specifying the name of a timestamp tag and the sample rate at this block, it keeps track of the time and will add the time to the first item of every packet. The name of the timestamp tag is usually 'rx_time' (see, e.g., gr::uhd::usrp_source::make()). The time value must be specified in the UHD time format.

- Other tags are simply stored and updated. As an example, the user might want to know the rx frequency, which UHD stores in the rx_freq tag. In this case, add the tag name 'rx_freq' to the list of `special_tags`. This block will then always save the most current value of 'rx_freq' and add it to the beginning of every packet.

gr::basic_block
gr::block
gr::digital::header_payload_demux
gr::messages::msg_accepter
gr::msg_accepter
std::enable_shared_from_this< basic_block >
gr::basic_block
d_name
d_symbol_alias
d_symbol_name
d_input_signature
d_output_signature
d_debug_logger
d_logger
msg_queue
d_rpc_vars
d_message_subscribers
gr::block
d_max_output_buffer
d_min_output_buffer
d_pmt_done
d_system_port
gr::digital::header_payload_demux
gr::messages::msg_accepter
gr::msg_accepter
std::basic_string< Char >
std::enable_shared_from_this< basic_block >
std::map< pmt::pmt_t, msg_queue_t, msg_queue_comparator >
std::shared_ptr< io_signature >
std::shared_ptr< logger >
std::shared_ptr< pmt_base >
std::shared_ptr< rpcbasic_base >
std::string
std::vector< long >
std::vector< rpcbasic_sptr >
elements
p
- gr::digital::header_payload_demux
  _post
- gr::digital::header_payload_demux
  active_thread_priority
- gr::digital::header_payload_demux
  add_item_tag
- gr::digital::header_payload_demux
  add_item_tag
- gr::digital::header_payload_demux
  alias
- gr::digital::header_payload_demux
  alias_pmt
- gr::digital::header_payload_demux
  alias_set
- gr::digital::header_payload_demux
  alignment
- gr::digital::header_payload_demux
  allocate_buffer
- gr::digital::header_payload_demux
  allocate_detail
- gr::digital::header_payload_demux
  basic_block
- gr::digital::header_payload_demux
  basic_block
- gr::digital::header_payload_demux
  BLACK
- gr::digital::header_payload_demux
  blkd_input_timer_value
- gr::digital::header_payload_demux
  block
- gr::digital::header_payload_demux
  block
- gr::digital::header_payload_demux
  check_topology
- gr::digital::header_payload_demux
  clear_finished
- gr::digital::header_payload_demux
  color
- gr::digital::header_payload_demux
  consume
- gr::digital::header_payload_demux
  consume_each
- gr::digital::header_payload_demux
  d_blkd_input_timer_value
- gr::digital::header_payload_demux
  d_color
- gr::digital::header_payload_demux
  d_debug_logger
- gr::digital::header_payload_demux
  d_input_signature
- gr::digital::header_payload_demux
  d_logger
- gr::digital::header_payload_demux
  d_max_output_buffer
- gr::digital::header_payload_demux
  d_message_subscribers
- gr::digital::header_payload_demux
  d_min_output_buffer
- gr::digital::header_payload_demux
  d_name
- gr::digital::header_payload_demux
  d_output_signature
- gr::digital::header_payload_demux
  d_pmt_done
- gr::digital::header_payload_demux
  d_rpc_set
- gr::digital::header_payload_demux
  d_rpc_vars
- gr::digital::header_payload_demux
  d_setlock
- gr::digital::header_payload_demux
  d_symbol_alias
- gr::digital::header_payload_demux
  d_symbol_name
- gr::digital::header_payload_demux
  d_symbolic_id
- gr::digital::header_payload_demux
  d_system_port
- gr::digital::header_payload_demux
  d_unique_id
- gr::digital::header_payload_demux
  declare_sample_delay
- gr::digital::header_payload_demux
  declare_sample_delay
- gr::digital::header_payload_demux
  delete_head_nowait
- gr::digital::header_payload_demux
  detail
- gr::digital::header_payload_demux
  dispatch_msg
- gr::digital::header_payload_demux
  empty_handled_p
- gr::digital::header_payload_demux
  empty_handled_p
- gr::digital::header_payload_demux
  empty_p
- gr::digital::header_payload_demux
  empty_p
- gr::digital::header_payload_demux
  enable_update_rate
- gr::digital::header_payload_demux
  erase_msg
- gr::digital::header_payload_demux
  expand_minmax_buffer
- gr::digital::header_payload_demux
  finished
- gr::digital::header_payload_demux
  fixed_rate
- gr::digital::header_payload_demux
  fixed_rate_ninput_to_noutput
- gr::digital::header_payload_demux
  fixed_rate_noutput_to_ninput
- gr::digital::header_payload_demux
  forecast
- gr::digital::header_payload_demux
  general_work
- gr::digital::header_payload_demux
  get_iterator
- gr::digital::header_payload_demux
  get_msg_map
- gr::digital::header_payload_demux
  get_tags_in_range
- gr::digital::header_payload_demux
  get_tags_in_range
- gr::digital::header_payload_demux
  get_tags_in_window
- gr::digital::header_payload_demux
  get_tags_in_window
- gr::digital::header_payload_demux
  GREY
- gr::digital::header_payload_demux
  has_msg_handler
- gr::digital::header_payload_demux
  has_msg_port
- gr::digital::header_payload_demux
  history
- gr::digital::header_payload_demux
  identifier
- gr::digital::header_payload_demux
  input_signature
- gr::digital::header_payload_demux
  insert_tail
- gr::digital::header_payload_demux
  is_pc_rpc_set
- gr::digital::header_payload_demux
  is_rpc_set
- gr::digital::header_payload_demux
  is_set_max_noutput_items
- gr::digital::header_payload_demux
  is_unaligned
- gr::digital::header_payload_demux
  log_level
- gr::digital::header_payload_demux
  make
- gr::digital::header_payload_demux
  max_noutput_items
- gr::digital::header_payload_demux
  max_output_buffer
- gr::digital::header_payload_demux
  message_port_is_hier
- gr::digital::header_payload_demux
  message_port_is_hier_in
- gr::digital::header_payload_demux
  message_port_is_hier_out
- gr::digital::header_payload_demux
  message_port_pub
- gr::digital::header_payload_demux
  message_port_register_in
- gr::digital::header_payload_demux
  message_port_register_out
- gr::digital::header_payload_demux
  message_port_sub
- gr::digital::header_payload_demux
  message_port_unsub
- gr::digital::header_payload_demux
  message_ports_in
- gr::digital::header_payload_demux
  message_ports_out
- gr::digital::header_payload_demux
  message_subscribers
- gr::digital::header_payload_demux
  min_noutput_items
- gr::digital::header_payload_demux
  min_output_buffer
- gr::digital::header_payload_demux
  mp_relative_rate
- gr::digital::header_payload_demux
  msg_accepter
- gr::digital::header_payload_demux
  msg_queue
- gr::digital::header_payload_demux
  name
- gr::digital::header_payload_demux
  nitems_read
- gr::digital::header_payload_demux
  nitems_written
- gr::digital::header_payload_demux
  nmsgs
- gr::digital::header_payload_demux
  no_pc_rpc
- gr::digital::header_payload_demux
  notify_msg_neighbors
- gr::digital::header_payload_demux
  output_multiple
- gr::digital::header_payload_demux
  output_multiple_set
- gr::digital::header_payload_demux
  output_signature
- gr::digital::header_payload_demux
  pc_input_buffers_full
- gr::digital::header_payload_demux
  pc_input_buffers_full
- gr::digital::header_payload_demux
  pc_input_buffers_full_avg
- gr::digital::header_payload_demux
  pc_input_buffers_full_avg
- gr::digital::header_payload_demux
  pc_input_buffers_full_var
- gr::digital::header_payload_demux
  pc_input_buffers_full_var
- gr::digital::header_payload_demux
  pc_noutput_items
- gr::digital::header_payload_demux
  pc_noutput_items_avg
- gr::digital::header_payload_demux
  pc_noutput_items_var
- gr::digital::header_payload_demux
  pc_nproduced
- gr::digital::header_payload_demux
  pc_nproduced_avg
- gr::digital::header_payload_demux
  pc_nproduced_var
- gr::digital::header_payload_demux
  pc_output_buffers_full
- gr::digital::header_payload_demux
  pc_output_buffers_full
- gr::digital::header_payload_demux
  pc_output_buffers_full_avg
- gr::digital::header_payload_demux
  pc_output_buffers_full_avg
- gr::digital::header_payload_demux
  pc_output_buffers_full_var
- gr::digital::header_payload_demux
  pc_output_buffers_full_var
- gr::digital::header_payload_demux
  pc_throughput_avg
- gr::digital::header_payload_demux
  pc_work_time
- gr::digital::header_payload_demux
  pc_work_time_avg
- gr::digital::header_payload_demux
  pc_work_time_total
- gr::digital::header_payload_demux
  pc_work_time_var
- gr::digital::header_payload_demux
  post
- gr::digital::header_payload_demux
  processor_affinity
- gr::digital::header_payload_demux
  produce
- gr::digital::header_payload_demux
  relative_rate
- gr::digital::header_payload_demux
  relative_rate_d
- gr::digital::header_payload_demux
  relative_rate_i
- gr::digital::header_payload_demux
  remove_item_tag
- gr::digital::header_payload_demux
  remove_item_tag
- gr::digital::header_payload_demux
  replace_buffer
- gr::digital::header_payload_demux
  reset_perf_counters
- gr::digital::header_payload_demux
  rpc_set
- gr::digital::header_payload_demux
  sample_delay
- gr::digital::header_payload_demux
  set_alignment
- gr::digital::header_payload_demux
  set_blkd_input_timer_value
- gr::digital::header_payload_demux
  set_block_alias
- gr::digital::header_payload_demux
  set_color
- gr::digital::header_payload_demux
  set_detail
- gr::digital::header_payload_demux
  set_fixed_rate
- gr::digital::header_payload_demux
  set_history
- gr::digital::header_payload_demux
  set_input_signature
- gr::digital::header_payload_demux
  set_inverse_relative_rate
- gr::digital::header_payload_demux
  set_is_unaligned
- gr::digital::header_payload_demux
  set_log_level
- gr::digital::header_payload_demux
  set_max_noutput_items
- gr::digital::header_payload_demux
  set_max_output_buffer
- gr::digital::header_payload_demux
  set_max_output_buffer
- gr::digital::header_payload_demux
  set_min_noutput_items
- gr::digital::header_payload_demux
  set_min_output_buffer
- gr::digital::header_payload_demux
  set_min_output_buffer
- gr::digital::header_payload_demux
  set_msg_handler
- gr::digital::header_payload_demux
  set_output_multiple
- gr::digital::header_payload_demux
  set_output_signature
- gr::digital::header_payload_demux
  set_processor_affinity
- gr::digital::header_payload_demux
  set_relative_rate
- gr::digital::header_payload_demux
  set_relative_rate
- gr::digital::header_payload_demux
  set_tag_propagation_policy
- gr::digital::header_payload_demux
  set_thread_priority
- gr::digital::header_payload_demux
  set_unaligned
- gr::digital::header_payload_demux
  setup_pc_rpc
- gr::digital::header_payload_demux
  setup_rpc
- gr::digital::header_payload_demux
  shared_from_base
- gr::digital::header_payload_demux
  sptr
- gr::digital::header_payload_demux
  start
- gr::digital::header_payload_demux
  stop
- gr::digital::header_payload_demux
  symbol_name
- gr::digital::header_payload_demux
  symbolic_id
- gr::digital::header_payload_demux
  system_handler
- gr::digital::header_payload_demux
  tag_propagation_policy
- gr::digital::header_payload_demux
  tag_propagation_policy_t
- gr::digital::header_payload_demux
  thread_priority
- gr::digital::header_payload_demux
  to_basic_block
- gr::digital::header_payload_demux
  TPP_ALL_TO_ALL
- gr::digital::header_payload_demux
  TPP_CUSTOM
- gr::digital::header_payload_demux
  TPP_DONT
- gr::digital::header_payload_demux
  TPP_ONE_TO_ONE
- gr::digital::header_payload_demux
  unaligned
- gr::digital::header_payload_demux
  unique_id
- gr::digital::header_payload_demux
  unset_max_noutput_items
- gr::digital::header_payload_demux
  unset_processor_affinity
- gr::digital::header_payload_demux
  update_rate
- gr::digital::header_payload_demux
  vcolor
- gr::digital::header_payload_demux
  WHITE
- gr::digital::header_payload_demux
  WORK_CALLED_PRODUCE
- gr::digital::header_payload_demux
  WORK_DONE
- gr::digital::header_payload_demux
  work_return_t
- gr::digital::header_payload_demux
  ~basic_block
- gr::digital::header_payload_demux
  ~block
- gr::digital::header_payload_demux
  ~msg_accepter