/* Copyright (c) 2007 - 2012 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$ */

/*=== Radio Applications ====================================================*/

/**
 @ingroup grpApp

 @defgroup grpAppRdiag Radio Diagnostics Application

 @brief <div style="background-color:#e6e6ff;">
        This application provides a framework for testing the radio
        functions.</div>

The basic functions of the transceiver, e.g. setting channel, adjusting
power and transmission/reception of frames can be done with hotkeys.
The application is usefull to check if a new board definition is valid
or a hardware platform works as expected.

@code
 avr-size install/bin/rdiag_rdk230.hex
   text    data     bss     dec     hex filename
      0    7960       0    7960    1f18 install/bin/rdiag_rdk230.hex
@endcode

    @section secAppRdiagUse Usage

    - Load the file @c "install/bin/rdiag_<board>.hex" to your hardware.
    - After starting a terminal and connecting the hardware

@code
Radio Diag 0.12                                                                                                                                                 >RADIO INIT: OK
>RADIO INIT: OK
@endcode

    - Press @b h to display a help screen

@code
i/I : show / show and reset statistic
+/- : incr./decr. channel
P/p : incr./decr. power
C/c : incr./decr. CCA mode
o   : set state OFF
t   : set state TX
r   : set state RX
s   : send a test frame
R   : toggle RXON_IDLE parameter
V/v : incr./decr. verbosity (0...2)
@endcode

    - Press @b i to display a statistic of the radio. <br>
     If the key @b I is pressed, the statistic values are
     reset to 0 after printing.

@code
>STAT duration: 33 ticks
 RX: frames: 12 crcerr: 12
 RX: channel 26 avg rssi: 0 avg lqi:  0
 TX: frames: 0
@endcode

   - with the keys @b o (TRX_OFF), @b r (TRX_RX), @b t (TRX_TX), the radio can be set into the
   basic states

@code
>SATE_OFF
>SATE_RX
>SATE_TX
@endcode

  - with the keys @b + and @b - the radio channel can be selected (11...26).
   The initial channel after chip reset is 11 (hardware feature).

@code
>CHAN: 12
>CHAN: 11
>CHAN: 26
@endcode

 - with @b p and @b P the transmit power is modified.
   The numbers 0 ... 15 represent the power values given in the data sheet
   of the AT86RF230
 - with @b c and @b C the CCA mode is switched (0...3)

@code
>PWR: 9
>PWR: 10
>CCA: 0
>CCA: 3
@endcode

 - with @b s a single test frame is send.
 - with @b S a test frame is send continously (until @b S is pressed).

@code
>SEND len=42
0000  01 00 02 55 55 55 55 55 55 55 55 55 55 55 55 55
0010  55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55
0020  55 55 55 55 55 55 55 55 00 00
>SEND CONTINOUS START
>SEND CONTINOUS STOP
@endcode

 - with @b R the transceiver state, while idle is selected
   - 1 after sending a frame, the transceiver is set to state TRX_RX
   - 0 after sending a frame, the transceiver is set to state TRX_OFF

@code
>RXON_IDLE: 1
>RXON_IDLE: 0
@endcode

 - with @b V and @b v the verbose level can be changed between 0..2
   - at 0 : nothing about TX and RX events is printed
   - at 1 : frame parameters for TX and RX events are printed
   - at 1 : the frame contents is also dumped
 - in case of many events, not all messages can be printed and
   display will miss information

@code
>VERBOSE: 0
>VERBOSE: 1
++FRAME len=117, crc=238, lqi=0 rssi=0
++FRAME len=31, crc=192, lqi=0 rssi=0
>SEND len=42
>VERBOSE: 2
++FRAME len=71, crc=119, lqi=0 rssi=0
0000  24 d9 80 79 eb b1 91 cf 6a ab 14 21 f7 f0 ce 6c
0010  6e a6 6c a1 16 37 72 e4 e7 60 56 20 66 27 31 42
0020  41 db 82 66 36 54 88 37 57 37 47 73 1c 7a d7 72
0030  6a 3f 40 82 17 c5 27 24 1d 1e 16 a6 52 71 59 64
0040  66 22 4c 32 71 37 53
>SEND len=42
0000  01 00 03 55 55 55 55 55 55 55 55 55 55 55 55 55
0010  55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55
0020  55 55 55 55 55 55 55 55 00 00
@endcode

*/

/**
 @ingroup grpApp

 @defgroup grpAppWuart Wireless UART Firmware

 @brief <div style="background-color:#e6e6ff;">
        This application implements a simple configurable wirless UART.</div>

*/

/**
 @page pgWuart Wireless UART

 The wireless UART can be used to communicate between two PCs via a RF
 link, or to communicate between a PC and an autnomous sensor/actor
 node. The WUART application starts on a fixed channel and is automatically
 in a transparent data mode.

@note
 The programm documentation of the firmware can be found in
 @ref grpAppWuart "this section".

 After a reset of the firmware, the programm prints a startup message
 and is then in the data transmission mode.

 The startup message can be used toidentify the baudrate, that is configured at
 compile time. The startup message is one line of text and contains the following
 information:

<pre>
Wuart 0.3 chan=11 radio 83.4 cfg F
      |    |         |        |
      |    |         |        +... configuration read from flash (F) or EEPROM (E)
      |    |         +............ values of transceivers PART_NUM.VERSION_NUM register
      |    +...................... configured IEEE radio channel
      +........................... application version
</pre>

After printing this startup message the WUART application is in data transmission
mode, that means that the payload of incoming frames is printed on the serial
interface and incoming data from the serial interface are sent as IEEE 802.15.4
frames.

@section secWuartIf Configuration

The wireless UART has a configuration menue, that can be reached by typing the
<a href="http://en.wikipedia.org/wiki/Time_Independent_Escape_Sequence">
Hayes 302 break sequence</a>: <tt>pause +++ pause</tt>. After entering this sequence
the following menu will appear in the terminal window:

<pre>
MENU:
[a] node address: 0x5
    peer address: 0x4
[c] channel:      11
[r] reset changes
[e] save and exit
[q] discard chadiscard changes and exit
</pre>

Pressing the letter in the square brackets will query you at a prompt for a
new parameter value. Pressing "e" stores the current settings in the EEPROM.
After pressing "e" or "q" the application returns to data mode.

@section secAppWuartProto WUART Protocol

The wireless UART uses the simple P2P air protocol. It assumes IEEE 802.15.4
data frames with 16 bit adressing and PAN-ID compression. The following frame
contains just one payload byte (7), the ASCII letter 'c':

<pre>
Frame Bytes:
0000  41 88 02 42 42 07 00 06 00 40 55 63 e9 b1         A..BB....@Uc..
      +---+ ++ +---+ +---+ +---+ +---+ ++ +---+
       (1)  (2) (3)   (4)   (5)   (6)  (7) (8)

Protocoll Data:
Frame 282: 14 bytes on wire (112 bits), 14 bytes captured (112 bits)
IEEE 802.15.4 Data, Dst: 0x0007, Src: 0x0006
P2P Protocol Data
    FCF:   0x4188               (1)
    Seq:        2               (2)
    pan:   0x4242               (3)
    to:    0x0007               (4)
    from:  0x0006               (5)
    cmd:   P2P_WUART_DATA (64)  (6a)
    mode:  85                   (6b)
    sdata: c                    (7)
    FCS:   0xb1e9               (8)
</pre>

*/

/**
 @ingroup grpApp

 @defgroup grpAppWiBo WiBo

 @brief <div style="background-color:#e6e6ff;">
        This application implements a wireless Bootloader</div>

 The wireless bootloader WiBo consists of three main parts
  - The bootloader app itself, residing in the bootloader section of the remote nodes
  - The host application running on board connected to a PC, this can be different from the target remote boards
  - A python class that implements all functions required for flashing firmware
  @dot
  graph "a"{

  "BOOTLAPP1" [ label="BootlApp" shape=box ]
  "BOOTLAPP2" [ label="BootlApp" shape=box ]
  "BOOTLAPP3" [ label="BootlApp" shape=box ]
  "BOOTLAPP4" [ label="BootlApp" shape=box ]
  "HOSTAPP" [ label="HostApp" shape=box ]
  "PYHOST"  [ label="PyHost" shape=box ]
  }
  @enddot
*/
