[Commit-gnuradio] [gnuradio] 01/02: docs: more documentation.

[git]

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

trondeau pushed a commit to branch master
in repository gnuradio.

commit 720f55287c5fe5cd3d7d6541f13382f3500f7f85
Author: Tom Rondeau <address@hidden>
Date:   Wed Apr 23 18:34:11 2014 -0400

    docs: more documentation.
    
    Stealing some of Martin Braun's PMT tutorial work for the pmt page. Added 
more info on constellations.
---
 docs/doxygen/other/pmt.dox                         | 128 +++++++++++++++++++++
 .../include/gnuradio/rpcregisterhelpers.h          |   2 +-
 gr-digital/doc/digital.dox                         |  22 ++++
 3 files changed, 151 insertions(+), 1 deletion(-)

diff --git a/docs/doxygen/other/pmt.dox b/docs/doxygen/other/pmt.dox
index 04f58aa..9ae4bcd 100644
--- a/docs/doxygen/other/pmt.dox
+++ b/docs/doxygen/other/pmt.dox
@@ -9,6 +9,134 @@ message passing interfaces. The most complete list of PMT 
function is,
 of course, the source code, specifically the header file pmt.h. This
 manual page summarizes the most important features and points of PMTs.
 
+Let's dive straight into some Python code and see how we can use
+PMTs:
+
+\code
+>>> import pmt
+>>> P = pmt.from_long(23)
+>>> type(P)
+<class 'pmt.pmt_swig.swig_int_ptr'>
+>>> print P
+23
+>>> P2 = pmt.from_complex(1j)
+>>> type(P2)
+<class 'pmt.pmt_swig.swig_int_ptr'>
+>>> print P2
+0+1i
+>>> pmt.is_complex(P2)
+True
+\endcode
+
+First, the pmt module is imported. We assign two values (P and P2)
+with PMTs using the from_long() and from_complex() calls,
+respectively. As we can see, they are both of the same type! This
+means we can pass these variables to C++ through SWIG, and C++ can
+handle this type accordingly.
+
+The same code as above in C++ would look like this:
+
+\code
+#include <pmt/pmt.h>
+// [...]
+pmt::pmt_t P = pmt::from_long(23);
+std::cout << P << std::endl;
+pmt::pmt_t P2 = pmt::from_complex(gr_complex(0, 1)); // Alternatively: 
pmt::from_complex(0, 1)
+std::cout << P2 << std::endl;
+std::cout << pmt::is_complex(P2) << std::endl;
+\endcode
+
+Two things stand out in both Python and C++: First we can simply print
+the contents of a PMT. How is this possible? Well, the PMTs have
+in-built capability to cast their value to a string (this is not
+possible with all types, though). Second, PMTs must obviously know
+their type, so we can query that, e.g. by calling the is_complex()
+method.
+
+When assigning a non-PMT value to a PMT, we can use the from_*
+methods, and use the to_* methods to convert back:
+
+\code
+pmt::pmt_t P_int = pmt::from_long(42);
+int i = pmt::to_long(P_int);
+pmt::pmt_t P_double = pmt::from_double(0.2);
+double d = pmt::to_double(P_double);
+\endcode
+
+String types play a bit of a special role in PMTs, as we will see
+later, and have their own converter:
+
+\code
+pmt::pmt_t P_str = pmt::string_to_symbol("spam");
+pmt::pmt_t P_str2 = pmt::intern("spam");
+std::string str = pmt::symbol_to_string(P_str);
+\endcode
+
+The pmt::intern is another way of saying pmt::string_to_symbol.
+
+In Python, we can make use of the weak typing, and there's actually a
+helper function to do these conversions (C++ also has a helper
+function for converting to PMTs called pmt::mp(), but its less
+powerful, and not quite as useful, because types are always strictly
+known in C++):
+
+\code
+P_int = pmt.to_pmt(42)
+i = pmt.to_python(P_int)
+P_double = pmt.to_pmt(0.2)
+d = pmt.to_double(P_double)
+\endcode
+
+On a side note, there are three useful PMT constants, which can be
+used in both Python and C++ domains. In C++, these can be used as
+such:
+
+\code
+pmt::pmt_t P_true = pmt::PMT_T;
+pmt::pmt_t P_false = pmt::PMT_F;
+pmt::pmt_t P_nil = pmt::PMT_NIL;
+\endcode
+
+In Python:
+
+\code
+P_true = pmt.PMT_T
+P_false = pmt.PMT_F
+P_nil = pmt.PMT_NIL
+\endcode
+
+pmt.PMT_T and pmt.PMT_F are boolean PMT types.
+
+To be able to go back to C++ data types, we need to be able to find
+out the type from a PMT. The family of is_* methods helps us do that:
+
+\code
+double d;
+if (pmt::is_integer(P)) {
+    d = (double) pmt::to_long(P);
+} else if (pmt::is_real(P)) {
+    d = pmt::to_double(P);
+} else {
+    // We really expected an integer or a double here, so we don't know what 
to do
+    throw std::runtime_error("expected an integer!");
+}
+\endcode
+
+It is important to do type checking since we cannot unpack a PMT of
+the wrong data type.
+
+We can compare PMTs without knowing their type by using the
+pmt::equal() function:
+
+\code
+if (pmt::eq(P_int, P_double)) {
+    std::cout << "Equal!" << std::endl; // This line will never be reached
+\endcode
+
+The rest of this page provides more depth into how to handle different
+data types with the PMT library.
+
+
 
 \section datatype PMT Data Type
 
diff --git a/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h 
b/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h
index ce21b96..86650a7 100644
--- a/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h
+++ b/gnuradio-runtime/include/gnuradio/rpcregisterhelpers.h
@@ -1330,7 +1330,7 @@ public:
    * \param def          Expected default value the parameter can hold
    * \param units_       A string to describe what units to represent the 
variable with
    * \param desc_        A string to describing the variable.
-   * \param minpriv_     The required minimum privilege level
+   * \param minpriv      The required minimum privilege level
    * \param display_     The display mask
    */
   rpcbasic_register_variable_rw(
diff --git a/gr-digital/doc/digital.dox b/gr-digital/doc/digital.dox
index 48feda3..5f2b3bb 100644
--- a/gr-digital/doc/digital.dox
+++ b/gr-digital/doc/digital.dox
@@ -348,6 +348,28 @@ single bit of data. A block like 'pack_k_bits' can be used 
following
 this to convert the data back into bytes.
 
 
+\section digital_constellation_modulator Constellation Modulator
+
+The Constellation Modulator, Constellation Receiver, and Constellation
+Decoder can all take Constellation Objects to define what they are
+meant to transmit and receive.
+
+The gr::digital::constellation_modulator block takes as a parameter
+the reference to the constellation object. The block is very generic
+in that the mapping from bits to symbols is done based on the
+constellation object passed to it. The modulator block requires packed
+bits as the input stream (that is, all 8 bits of the stream contain
+information).
+
+The other parameters of this block include a setting as to whether or
+not to differentially encode the symbols, the number of samples per
+symbols, and the excess bandwidth of the transmitted pulse-shaped
+signal.
+
+We can set up the transmitter using the constellation modulator block
+and use the same constellation object at the receiver so we know the
+same constellation settings are being used.
+
 \section digital_softbits Support for Soft Decisions
 
 To support soft decisions of the receivers instead of the current hard