[Commit-gnuradio] [gnuradio] 07/13: documentation: Bit handling gotchas explained

[git]

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

jcorgan pushed a commit to branch master
in repository gnuradio.

commit 850d5ca30cd10a3cf1edaf46234690c5dca3e5c4
Author: Tim Kuester <address@hidden>
Date:   Tue Apr 15 16:59:53 2014 -0400

    documentation: Bit handling gotchas explained
---
 gr-blocks/include/gnuradio/blocks/pack_k_bits_bb.h   |  9 +++++++++
 gr-blocks/include/gnuradio/blocks/short_to_char.h    |  6 ++++++
 gr-blocks/include/gnuradio/blocks/unpack_k_bits_bb.h |  8 ++++++++
 gr-digital/python/digital/psk.py                     | 18 +++++++++++++-----
 4 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/gr-blocks/include/gnuradio/blocks/pack_k_bits_bb.h 
b/gr-blocks/include/gnuradio/blocks/pack_k_bits_bb.h
index c8c4378..cd05772 100644
--- a/gr-blocks/include/gnuradio/blocks/pack_k_bits_bb.h
+++ b/gr-blocks/include/gnuradio/blocks/pack_k_bits_bb.h
@@ -32,6 +32,15 @@ namespace gr {
     /*!
      * \brief Converts a stream of bytes with 1 bit in the LSB to a
      * byte with k relevent bits.
+     *
+     * This block takes in K bytes at a time, and uses the least significant
+     * bit to form a new byte.
+     *
+     * Example:
+     * k = 4
+     * in = [0,1,0,1, 0x81,0x00,0x00,0x00]
+     * out = [0x05, 0x08]
+     *
      * \ingroup byte_operators_blk
      */
     class BLOCKS_API pack_k_bits_bb : virtual public sync_decimator
diff --git a/gr-blocks/include/gnuradio/blocks/short_to_char.h 
b/gr-blocks/include/gnuradio/blocks/short_to_char.h
index de4df62..22a157d 100644
--- a/gr-blocks/include/gnuradio/blocks/short_to_char.h
+++ b/gr-blocks/include/gnuradio/blocks/short_to_char.h
@@ -31,6 +31,12 @@ namespace gr {
 
     /*!
      * \brief Convert stream of shorts to a stream of chars.
+     *
+     * This block strips off the least significant byte from the
+     * short value. 
+     * 
+     * [0x00ff, 0x0ff0, 0xff00] => [0x00, 0x0f, 0xff]
+     *
      * \ingroup type_converters_blk
      */
     class BLOCKS_API short_to_char : virtual public sync_block
diff --git a/gr-blocks/include/gnuradio/blocks/unpack_k_bits_bb.h 
b/gr-blocks/include/gnuradio/blocks/unpack_k_bits_bb.h
index 9268195..09d7ae9 100644
--- a/gr-blocks/include/gnuradio/blocks/unpack_k_bits_bb.h
+++ b/gr-blocks/include/gnuradio/blocks/unpack_k_bits_bb.h
@@ -31,6 +31,14 @@ namespace gr {
     
     /*!
      * \brief Converts a byte with k relevent bits to k output bytes with 1 
bit in the LSB.
+     *
+     * This block picks the K least significant bits from a byte, and expands
+     * them into K bytes of 0 or 1.
+     *
+     * Example:
+     * k = 4
+     * in = [0xf5, 0x08]
+     * out = [0,1,0,1, 1,0,0,0]
      * \ingroup byte_operators_blk
      */
     class BLOCKS_API unpack_k_bits_bb : virtual public sync_interpolator
diff --git a/gr-digital/python/digital/psk.py b/gr-digital/python/digital/psk.py
index 1816ffb..0e0c65e 100644
--- a/gr-digital/python/digital/psk.py
+++ b/gr-digital/python/digital/psk.py
@@ -85,9 +85,15 @@ class psk_mod(generic_mod):
     """
     Hierarchical block for RRC-filtered PSK modulation.
     
-    The input is a byte stream (unsigned char) and the
-    output is the complex modulated signal at baseband.
-    
+    The input is a byte stream (unsigned char), treated as a series of packed
+    symbols. Symbols are grouped from MSB to LSB.
+
+    The output is the complex modulated signal at baseband, with a given number
+    of samples per symbol.
+
+    If "Samples/Symbol" is 2, and "Number of Constellation Points" is 4, a
+    single byte contains four symbols, and will produce eight samples.
+
     Args:
         constellation_points: Number of constellation points (must be a power 
of two) (integer).
         mod_code: Whether to use a gray_code (digital.mod_codes.GRAY_CODE) or 
not (digital.mod_codes.NO_CODE).
@@ -113,8 +119,10 @@ class psk_demod(generic_demod):
     """
     Hierarchical block for RRC-filtered PSK modulation.
     
-    The input is a byte stream (unsigned char) and the
-    output is the complex modulated signal at baseband.
+    The input is a complex modulated signal at baseband.
+
+    The output is a stream of bytes, each representing a recovered bit.
+    The most significant bit is reported first.
 
     Args:
         constellation_points: Number of constellation points (must be a power 
of two) (integer).