[Commit-gnuradio] [gnuradio] 01/02: docs: Added section on message commands

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch maint
in repository gnuradio.

commit 72e0c237e06e5214eb2706bd4ac732cef068161c
Author: Martin Braun <address@hidden>
Date:   Wed Apr 29 14:50:38 2015 -0700

    docs: Added section on message commands
---
 docs/doxygen/other/msg_passing.dox | 40 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/doxygen/other/msg_passing.dox 
b/docs/doxygen/other/msg_passing.dox
index df116c2..494ca03 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.
+
 */