gnuradio
blocks: add burst to stream block
Description
This adds a new block called Burst to Stream. The block transforms a bursty tagged stream into a continuous stream by inserting zeros in the output between packets whenever no packets are available at the input.
There are two main use cases for this block:
-
Using a packet transmitter that outputs a tagged stream with an SDR that does not support burst-mode, by converting the output of the packet transmitter into a continuous stream of samples at the rate required by the SDR.
-
Simulation of a packet transmitter by inserting gaps between the packets. In this way, a receiver used in the simulation will see these packets with gaps between them rather than back-to-back.
An example flowgraph to demonstrate the usage of this block is included.
Related Issue
No related issue.
Which blocks/areas does this affect?
gr-blocks. A new block is added.
Testing Done
There is a QA test for the new block, and the block has also been tested with the example flowgraph.
Checklist
- [x] I have read the CONTRIBUTING document.
- [x] I have squashed my commits to have one significant change per commit.
- [x] I have signed my commits before making this PR
- [x] My code follows the code style of this project. See GREP1.md.
- [ ] I have updated the documentation where necessary. -> Not done yet. I will add a wiki entry for this block when the PR is merged.
- [x] I have added tests to cover my changes, and all previous tests pass.
Note: the code for this block is licensed as MIT because it comes from a yet-unreleased OOT module that is licensed in that way. I guess this is okay, because including MIT code in a GPL-3.0-or-later codebase is fine, but if necessary, I can re-license the block as GPL-3.0-or-later.
Interesting!
Would probably make most sense directly feeding into an SDR hardware sink or a Throttle(2) block, as otherwise the buffer-filling nature of GR3 "scheduling" would produce a lot of zeros, right?
It this kind of like a piece of osh's (very outdated) gr-eventstream https://github.com/osh/gr-eventstream? It would be worth browsing that package to see if any of the additional features make sense.
Would probably make most sense directly feeding into an SDR hardware sink or a Throttle(2) block, as otherwise the buffer-filling nature of GR3 "scheduling" would produce a lot of zeros, right?
I'm not sure I understand what you mean. Do you mean connecting the output of this Burst to Stream block directly to an SDR sink or a Throttle, or do you mean skipping the Burst to Stream block altogether? If the former, then yes, you're right. The block following this one is supposed to "request input" at a steady rate rather than "greedily". Blocks that do this are any kind of hardware sink, the throttle block, and maybe some of the network sinks if they pass backpressure and the other endpoint reads at a steady rate (although for instance TCP OS buffers are usually huge, so this will probably give problems). If you connect another block to the output of Burst to Stream, (say Multiply Const), I guess that such block will ask for input in huge chunks, causing a lot of zeros to be produced.
If you connect another block to the output of Burst to Stream, (say Multiply Const), I guess that such block will ask for input in huge chunks, causing a lot of zeros to be produced.
Actually I should correct myself. From my experience, having some "math" blocks between Burst to Stream and the SDR Sink tends to work fine. For instance, a topology like this works fine to have multiple packet transmitters on the same SDR Sink (this is needed for transmitters that send packets independently, even for a USRP that supports burst mode transmission).
I guess that what happens is that since the SDR Sink is consuming data at a certain rate, the work() function for the Add block, and in turn the work() functions of the Burst to Stream blocks get called with an output buffer of a reasonable size (not too large). Probably looking into how this works in more detail goes into a rabbit hole of scheduling and transmit latency.
It this kind of like a piece of osh's (very outdated) gr-eventstream https://github.com/osh/gr-eventstream?
@willcode I'm not too familiar with gr-eventstream, so I can't say. I've been taking a look at the repo, but since it's for GR 3.7, it's difficult to test the examples to see what the blocks due. As a quick check, I've read through the XML GRC files to find blocks that have a stream input and output (since this, rather than using messages, is a fundamental feature of the block in this PR). The only two blocks I found (besides the Patterned Interleaver) that have this are:
https://github.com/osh/gr-eventstream/blob/master/grc/es_trigger_edge_f.xml https://github.com/osh/gr-eventstream/blob/master/grc/es_trigger_sample_timer.xml
And the "trigger" in their name makes me think they're unrelated to this Burst to Stream block.
This Burst to Stream block is somewhat similar to an old block that @balint256 wrote (I can't remember the name of the block or the OOT module, though). If I remember well, that block had two inputs, A and B. The block sent to the output whatever was present in input A, and if nothing was present it sent data from input B. So it behaved like a priority mux. Connecting a Null Source to B gives something similar to this Burst to Stream. While having two inputs is more flexible, because it allows to inject any kind of data as a filler between packets, I think that most of the time zero-filling is what is desired, so Burst to Stream can only do zero-filling because it makes the block simpler and more efficient.
I was thinking of the kind of logic in the source block:
https://github.com/osh/gr-eventstream/blob/master/grc/es_source.xml https://github.com/osh/gr-eventstream/blob/master/lib/es_source.cc
This is sort of a burst-to-stream with a built in throttle, so there is more control over latency. I can imagine that, if the block is constantly padding with zeros, and the user sends tagged streams at nearly the tx rate, that there things could get backed up.
https://github.com/osh/gr-eventstream/blob/master/lib/es_source.cc
I took a brief look at that code and it seems to me that the functionality of that block is as follows: Packets arrive to the block on a message input port. The packets contain a timestamp. The block produces the packets in the output at the specific time indicated in the packet timestamp (if a packet arrives too late to the block, there are several different policies to handle the situation). When there are no packets to be produced, the block produces zeros.
So the Burst to Stream block in this PR is similar to the EventStream Source in the particular case where all the packets are sent with a timestamp of zero (so they are guaranteed to arrive late) and the ASAP policy is used. An important difference is that the Burst to Stream input is a tagged stream and the EventStream Source input is a message port.
and the user sends tagged streams at nearly the tx rate, that there things could get backed up.
This is acceptable use. The block propagate backpressure upstream. The user can attempt to send packets even faster than the TX rate, and it will get backpressure to control the rate at which packets are generated. In this situation there will be no zeros inserted between packets, because there is always input available.