From 72e0c237e06e5214eb2706bd4ac732cef068161c Mon Sep 17 00:00:00 2001 From: Martin Braun <martin.braun@ettus.com> Date: Wed, 29 Apr 2015 14:50:38 -0700 Subject: docs: Added section on message commands --- docs/doxygen/other/msg_passing.dox | 40 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'docs/doxygen') 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. + */ -- cgit v1.2.3