diff options
| author | Johnathan Corgan <johnathan@corganlabs.com> | 2015-04-29 15:46:26 -0700 |
|---|---|---|
| committer | Johnathan Corgan <johnathan@corganlabs.com> | 2015-04-29 15:46:26 -0700 |
| commit | 4bf227c02c6f4ae59f285510b8faaa1686163894 (patch) | |
| tree | 210a130a3a897832450886da6822486ac90c256f /docs/doxygen | |
| parent | 70fecd437b264984569f6a4531dd3b424aced781 (diff) | |
| parent | efd2116fdf27892b93078be5b019b0d9bf3943aa (diff) | |
Merge branch 'master' into next
Diffstat (limited to 'docs/doxygen')
| -rw-r--r-- | docs/doxygen/other/msg_passing.dox | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/docs/doxygen/other/msg_passing.dox b/docs/doxygen/other/msg_passing.dox index df116c2ba1..494ca03921 100644 --- a/docs/doxygen/other/msg_passing.dox +++ b/docs/doxygen/other/msg_passing.dox @@ -311,4 +311,44 @@ file qa_pdu.py. There are some examples of using the message passing infrastructure through GRC in gr-blocks/examples/msg_passing. +\section msg_passing_commands Using messages as commands + +Messages can be used to send commands to blocks. Examples for this include: + +- gr::qtgui::freq_sink_c: The scaling of the frequency axis can be changed by messages +- gr::uhd::usrp_source and gr::uhd::usrp_sink: Many transceiver-related settings can + be manipulated through command messages, such as frequency, gain and LO offset +- gr::digital::header_payload_demux, which receives an acknowledgement from a header parser + block on how many payload items there are to process + +There is no special PMT type to encode commands, however, it is strongly recommended +to use one of the following formats: + +- pmt::cons(KEY, VALUE): This format is useful for commands that take a single value. + Think of KEY and VALUE as the argument name and value, respectively. For the case of + the QT GUI Frequency Sink, KEY would be "freq" and VALUE would be the new center frequency + in Hz. +- pmt::dict((KEY1: VALUE1), (KEY2: VALUE2), ...): This is basically the same as the + previous format, but you can provide multiple key/value pairs. This is particularly + useful when a single command takes multiple arguments which can't be broken into + multiple command messages (e.g., the USRP blocks might have both a timestamp and a + center frequency in a command message, which are closely associated). + +In both cases, all KEYs should be pmt::symbols (i.e. strings). VALUEs can be +whatever the block requires. + +It might be tempting to deviate from this format, e.g. the QT Frequency sink could +simply take a float value as a command message, and it would still work fine. +However, there are some very good reasons to stick to this format: + +- Interoperability: The more people use the standard format, the more likely it + is that blocks from different sources can work together +- Inspectability: A message debug block will display more useful information about + a message if its containing both a value and a key +- Intuition: This format is pretty versatile and unlikely to create situations + where it is not sufficient (especially considering that values are PMTs themselves). + As a counterexample, using positional arguments (something like "the first argument + is the frequency, the second the gain") is easily forgotten, or changed in one place + and not another, etc. + */ |