/* Copyright (c) 2007 Axel Wachtler
   All rights reserved.

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:

   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
   * Neither the name of the authors nor the names of its contributors
     may be used to endorse or promote products derived from this software
     without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   POSSIBILITY OF SUCH DAMAGE. */

/* $Id: transceiver.dox,v 1.6 2009/02/13 06:32:37 awachtler Exp $ */

/*===Transceiver Applications ===============================================*/

/**
  @defgroup grpAppTrx Applications based on Transceiver functions
 */


/**
 @ingroup grpAppTrx

 @defgroup grpAppSniffer Simple Sniffer and Scanner Application

 @brief <div style="background-color:#ccccff;">
        This application provides funtions for scanning
        and sniffing different radio channels.
        </div>


 The application provides two modes:
  - The @ref secScanMode "Scan Mode" scans over the selected channels and displays statistics
     of the received frames. The channel is switched after the time @ref SCAN_PERIOD_MS.
  - The @ref secSniffMode "Sniff Mode" receives on one selected channel and dumps the frames on the host
    interface. This mode can used for live capturing WPAN data with wireshark
    (see contibution guide for more details).

 @section secAppSnifferUse Usage

 The following commands are available in the terminal:

 \par Mode Commands:

  - @opt{idle}, Keys: @c I, @c &lt;SPACE&gt; \n
     Set application to idle mode and transceiver to state TRX_OFF.
  - @opt{scan}\n
     Scan for frames on the enabled channels
     (see also commands @c cmask, @c cmset and @c cmclr)
  - @opt{sniff}\n
     Start sniffing frames on the current channel and dump the
     received packets of the hostinterface (see command @c parms).

 \par Parameter Commands:

  - @opt{parms}\n
     Display current parameter settings.
  - @opt2{chan,CHAN}, Keys: @c + ,  @c - \n
     Set current channel (for sniffing). "+" increments the current
     channel by one, "-" decrements by one.
  - @opt2{cmclr,chan}\n
     Erase the channel bit in @c cmask.
  - @opt2{cmset,chan}\n
     Set the channel bit in @c cmask.
  - @opt2{cmask,mask}\n
     Set the 32 bit channel mask. @c mask can be a
     hexadecimal value, e.g. 0x07fff800
  - @opt2{cpage,page} \n
     Set current channel page (@b{not yet supported})
  - @opt2{drate,ratestr} \n
     Set current data rate of transceiver.
     ratestr = {BPSK{20,40}, OQPSK{100,200,250,400,500,1000,2000}}
  - @opt2{chkcrc,[0|1]} \n
     if 0, discard frames with invalid CRC, if 1, report also frames
     with invalid CRC.

@subsection secScanMode Scan Mode

The Scan Mode is started with the command @c scan.
The scanned channels can be configured with the channel mask
and the commands @c cmset, @c cmclr and @c cmask.

@par IEEE Channels, Channel Mask and Channel Page in Scan Mode

IEEE 802.15.4 uses a 32 bit channel mask. Since the standard
uses just 26 channels (0 for 868 MHz, 1-10 for 915 MHz and 11-26 for
2.4 GHz) the upper 5 bits of the channel mask are currently used by
the value channel page. The channel page identifies the modulation
method used.

In order to enable channel 15 in the channel mask for scanning, you
can use the command <tt>cmask 0x00008000</tt> or <tt>cmset 15</tt>.

<pre>
> parms
SUPP_CMSK: 0x07fff800 ....... shows the supported channels of the radio
CURR_CMSK: 0x04008800 ....... channel mask used for scanning (11,15,26)
CURR_CHAN: 11 ............... channel used for sniffing
CURR_PAGE: 0  ............... unsupported yet
</pre>

@par Display of the Scan Results

In scan mode the application switches from channel to channel and
collects the statistics of the received frames. The information
can be displayed in a terminal as table (see example below, which
scans only channels 11 and 15, cmask = 0x00008800).

<pre class="fragment">
> scan
Scanning channels, scan period 2000ms
             bad    Avg.         802.15.4 frames
chan   frm   crc   ed lqi      B     D     A     C  PER
*11      0     0    0   0      0     0     0     0    0
 12  n/a
 13  n/a
 14  n/a
 15     62     0   71 255      0    62     0     0    0
 16  n/a
 17  n/a
 18  n/a
 19  n/a
 20  n/a
 21  n/a
 22  n/a
 23  n/a
 24  n/a
 25  n/a
 26      1     1    0   0      0     0     0     0  100
=== ur 0 err 0 frames: 63 ===
</pre>

The columns of the table have the following meaning:

<pre class="fragment">
             bad    Avg.         802.15.4 frames
chan   frm   crc   ed lqi      B     D     A     C  PER
 |      |     |    |   |       |     |     |     |   +... Estimated packet error rate
 |      |     |    |   |       |     |     |     +....... number of rx'd command frames
 |      |     |    |   |       |     |     +............. number of rx'd ACK frames
 |      |     |    |   |       |     +................... number of rx'd data frames
 |      |     |    |   |       +......................... number of rx'd beacon frames
 |      |     |    |   +................................. average LQI of frames on this channel
 |      |     |    +..................................... average energy value frames on this channel
 |      |     +.......................................... number of frames with bad CRC
 |      +................................................ number of received frames
 +....................................................... channel number
</pre>

@subsection secSniffMode Sniffer Mode

The Sniff Mode is started with the command @c sniff. The channel
which should be monitored is set with the command @c chan.
In the sniff mode, each received frame is transfered over the host
interface to the PC application.

@par Data Transfer in Sniffer Mode



 The binary protocoll used for transfer the received frames
 over the host interface in sniff-mode has the following format:

 <pre class="fragment">
 +-------+--------+--------+------------+--------+
 | SOF   |  LEN   | TSTAMP | FRAMEDATA  | EOF    |
 +-------+--------+--------+------------+--------+
 | 1Byte | 1 Byte | 8 Byte | 1-127 Byte | 1 Byte |
 +-------+--------+--------+------------+--------+
 </pre>

  @param SOF       Start of frame field (0x01)
  @param LEN       Length of packet (size of time stamp and frame size) (8 ... 133)
  @param TSTAMP    Time structure (4 Byte seconds, 4 byte micro seconds)
  @param FRAMEDATA Octets of the frame (the data does not contain the IEEE
                   802.15.4 PHR with the reserved bit value).
  @param EOF       End of frame field.


@todo
  - Active Scan Mode per channel, to detect WPANs.
  - Fast Energy Scan over channels.
  - Parametric frame filter.
  - command for setting scan period

*/

/**
 @ingroup grpAppTrx

 @defgroup grpAppWgpio Wireless GPIO Application

 @brief <div style="background-color:#ccccff;">
        This application implements a simple configurable wirless digirtal IO module.</div>

 @par Overview

 The application uses 1 key for input and two LEDs for signalling the output,
 where LED0 represents the actor and LED1 gives status information, e.g. if a key press
 is received by another node.

 After power up, the application is in state @ref APP_RUNNING and is waiting for
 input events. When the key is pressed shortly, the local actor (if enabled) is processed
 and frame indicating a @ref CMD_SWITCH is sent. If this frame is received by another
 node, the actor of this node is updated and a @ref CMD_STATUS frame is sent.

 Each node can enter the configuration mode, when long pressing of the key is detected.
 In the configuration the node can be adjusted to be STANDBY (0), SWITCH (1), ACTOR (2) or
 SWACTOR (switch and actor, 3).

 @par Protocoll

 @section secAppWgpioUse Usage
 @underconstruction

*/
