root/ossiedev/branches/jgaeddert/0.8.0/components/README.txt @ 10684

=======================================================================
 
  ossie-liquid-components

=======================================================================

This directory contains the project repo for OSSIE components using the
liquid-dsp library.  It provides a massive simplification over
conventional OSSIE components projects by combining the entire build
system into one directory.  This speeds up build time significantly as
the configure script needs to be run only once for all the components.

These components require the liquid-dsp library installed, a free and
open-source signal processing library for software-defined radios. See
http://ganymede.ece.vt.edu for installation instructions, source code
respositories, and full documentation.

BUILD:
    $ ./reconf
    $ ./configure
    $ make

INSTALL:
    $ make install

The following components are available:
    complexFloat2Short
    complexShort2Float
    Channel
    FlexframeGen
    FlexframeSync
    FrameGen64
    FrameSync64
    PacketDecoder
    PacketEncoder
    PacketSink
    PacketSource

Here is a brief description of each

complexFloat2Short
complexShort2Float
    These components simply convert a complexFloat CORBA type to a
    complexShort (and vise versa).  This is useful for plotting, as the
    tools do not support complexFloat at the time these components were
    written.  Signal processing elements rely on floating-point data
    types to maintain a sufficient dynamic range.

Channel
    The channel component adds the following impairments:
      * CFO, carrier frequency offset
      * CPO, carrier phase offset
      * noise at a specific signal-to-noise ratio (assuming the RMS of the
        input signal is unity)
      * gain (maintains specific SNR level)
      * tau, fractional timing offset (not yet implemented)

FlexframeGen
FlexframeSync
    Generate a flexframe.
    Here are the available modulation schemes:
        bpsk, qpsk, psk<2..256>, dpsk<2..256>, qam<4..256>, apsk<4..128>,
        ask<2..256>, arb16opt, arb64vt
    (see A.1 at the end of this file for details).
    The generator accepts a header of exactly 8 bytes (anything else will
    result in an exception being thrown), and a payload of any reasonable
    length.

FrameGen64
FrameSync64
    Generate a frame64.  The header length is exactly 24 bytes and the payload
    is 64 bytes exactly. This is a simplified frame that does not allow
    adjustment of modulation and forward error-correction coding.

PacketDecoder
PacketEncoder
    Encode/decode packets using various forward error-correction codes (FEC).
    The input data are encoded using optional inner and outer codecs with an
    optional data validity check (either a cylic redundancy check or simple
    checksum).  See A.2 and A.3 at the end of this file for details.
    
PacketSink
PacketSource
    Generate/absorb random packets with headers.

======================================================
 A.1 Available modulation schemes
======================================================
Tabulated below is a list of all the digital modulation schemes available. The
first few types are generic to their constellation size (i.e.
2,4,8,16,32,...256); however not all combinations are available. For example
apsk only allows a minimum of M=4 points in the constellation and a maximum of
M=128. The last set of modulation schemes have a specific size.

    Generic types
    [psk]       phase-shift keying (psk2,psk4,psk8,...psk256)
    [dpsk]      differential phase-shift keying (dpsk2,dpsk4,...dpsk256)
    [ask]       amplitude-shift keying (ask2,ask4,ask8,...ask256)
    [qam]       quadrature amplitude-shift keying (qam4,qam8,qam16,...qam256)
    [apsk]      amplitude/phase-shift keying (apsk4,apsk8,apsk16,...apsk128)

    Specific types
    [bpsk]      specific BPSK
    [qpsk]      specific QPSK
    [arb16opt]  arbitrary modem (optimal 16-QAM)
    [arb64vt]   arbitrary modem (Virginia Tech logo)

======================================================
 A.2 Available forward error-correction codes
======================================================
Note that only the Hamming and repeat codes are available by default. The
convolutional and Reed-Solomon codes are available only if libfec is installed
(see http://www.ka9q.net/code/fec/). Details about installation can be found
by reading the liquid-dsp documentation (see the source code or
http://ganymede.ece.vt.edu).
    [none]      none
    [r3]        repeat(3)
    [r5]        repeat(5)
    [h74]       Hamming(7,4)
    [h84]       Hamming(8,4)
    [h128]      Hamming(12,8)
    [v27]       convolutional r1/2 K=7
    [v29]       convolutional r1/2 K=9
    [v39]       convolutional r1/3 K=9
    [v615]      convolutional r1/6 K=15
    [v27p23]    convolutional r2/3 K=7 (punctured)
    [v27p34]    convolutional r3/4 K=7 (punctured)
    [v27p45]    convolutional r4/5 K=7 (punctured)
    [v27p56]    convolutional r5/6 K=7 (punctured)
    [v27p67]    convolutional r6/7 K=7 (punctured)
    [v27p78]    convolutional r7/8 K=7 (punctured)
    [v29p23]    convolutional r2/3 K=9 (punctured)
    [v29p34]    convolutional r3/4 K=9 (punctured)
    [v29p45]    convolutional r4/5 K=9 (punctured)
    [v29p56]    convolutional r5/6 K=9 (punctured)
    [v29p67]    convolutional r6/7 K=9 (punctured)
    [v29p78]    convolutional r7/8 K=9 (punctured)
    [rs8]       Reed-Solomon, 223/255

======================================================
 A.3 Available data validity checks
======================================================
Tabulated below is a list of the available data validity checks. When no check
is used ('none') the data will always be returned as 'valid.' The available
cyclic redundancy checks range from 8 to 32 bits and are considerably stronger
than the simple 8-bit checksum.
    [none]      none
    [checksum]  checksum (8-bit)
    [crc8]      CRC (8-bit)
    [crc16]     CRC (16-bit)
    [crc24]     CRC (24-bit)
    [crc32]     CRC (32-bit)