/* Copyright (c) 2008 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: xmpl.dox,v 1.24 2011/01/08 19:47:19 awachtler Exp $ */

/**
 \ifnot NEWDOC

 @mainpage @uracoli Example Guide

 The @subpage pgXmplMain section describes how to use the example code
 and documents the examples.

 All software and documentation provided here, is released under the
 terms of the @subpage pgDevLicense "Modified BSD License".

 \endif
*/

/**
 \ifnot NEWDOC
 @page pgDevLicense License and Copyright

<pre>
\htmlinclude "LICENSE"
</pre>
 \endif
*/

/**
 @page pgXmplMain Examples

 The @uracoli examples illustrate the use of the various library functions.
 This simple programms operate the LEDs, the HIF or the radio transceiver.
 They can be used either for testing the hardware or as starting point for
 own applications.

 @section secXmplUsage Example Usage

 Each example consists of a C source file, a GNUMakefile that is used
 for command line builds and an aps-file for Atmel AvrStudio .
 Here are the files, that belong to the example @ref pgXmplHif.
 <pre>
     xmpl/xmpl.h .................... common defines for all examples
     xmpl/xmpl_hif.c ................ example source file
     xmpl/xmpl_hif.aps .............. AVR Studio file
     xmpl/xmpl_hif.mk ............... GNU Makefile
 </pre>

 @par Building on the Command Line

 The example can be build with command <tt>make -f xmpl_hif.mk TARGET</tt>.
 TARGET is either <b>all</b> (building this example for supported boards)
 or the name of the board to build for (see @ref pgBoards).

 Here is the log for building xmpl_hif.c for the board @ref secBoardrdk230 "rdk230".
 <pre>
 make -C install/xmpl/ -f xmpl_hif.mk rdk230
    make: Entering directory `[...]/install/xmpl'
    make -f xmpl_hif.mk BOARD=rdk230 MCU=atmega1281 F_CPU=8000000UL ./obj ./bin __xmpl_hif__
    make[1]: Entering directory `[...]/install/xmpl'
    avr-gcc -Wall -Wundef -Os -g -mmcu=atmega1281 -Wa,-adhlns=./obj/xmpl_hif_rdk230.lst -Drdk230 -DF_CPU=8000000UL -I../inc -I. -c -o obj/xmpl_hif_rdk230.o xmpl_hif.c
    avr-gcc -o bin/xmpl_hif_rdk230.elf -Wall -Wundef -Os -g -mmcu=atmega1281 -Wa,-adhlns=obj/xmpl_hif_rdk230.o -Drdk230 -DF_CPU=8000000UL -I../inc -I. obj/xmpl_hif_rdk230.o -L../lib -lradio_rdk230 -lio_rdk230
    avr-objcopy -O ihex bin/xmpl_hif_rdk230.elf bin/xmpl_hif_rdk230.hex
    make[1]: Leaving directory `[...]/install/xmpl'
    make: Leaving directory `[...]/install/xmpl'
 </pre>

 After make did run, the files <tt>bin/xmpl_hif_rdk230.elf</tt> and
 <tt>bin/xmpl_hif_rdk230.hex</tt> are created. The directory
 <tt>./obj</tt> stores temporary files that are created during the
 build.


 @par Building Examples with AvrStudio.

 Double click on the xmpl_hif.aps and AvrStudio starts with the project
 file. In the next step select "Project/Configuration Options", this opens
 the "Project Options" dialogue. In the section "General" there is a drop down
 list named "Active Configuration". Here you can select your board (see @ref pgBoards).

 Now click "Build" / "Build and Run" or type "Strg+F7" to build and flash the
 example.

 The result files for the AvrStudio build are stored in the directory with the
 name of the selected configuration, e.g. in this case "rdk230".

 @note Not every example is available for every board, e.g. since the board
 @ref secBoardtiny230 "tiny23x" has no UART interface, the examples that requires
 a HIF are not available.

 @section secXmplIoutil Ioutils Examples

  - @subpage pgXmplLed
  - @subpage pgXmplKey
  - @subpage pgXmplKeyEvents
  - @subpage pgXmplTmr
  - @subpage pgXmplHif
  - @subpage pgXmplDbg

 @section secXmplTrx Transceiver Examples

  - @subpage pgXmplTrxBase
  - @subpage pgXmplTrxTx
  - @subpage pgXmplTrxRx
  - @subpage pgXmplTrxEcho
  - @subpage pgXmplTrxTxAret
  - @subpage pgXmplTrxRxAack

 @section secXmplRadio Radio Examples

  - @subpage pgXmplRadio
  - @subpage pgXmplRadioRange
  - @subpage pgXmplLbufferTx
  - @subpage pgXmplLbufferRx
  - @subpage pgXmplRadioStream


 @section secXmplBoard Board Specfic Examples

 @par LittleGee231

  - @subpage pgXmplAccSimple

*/


/**
 @page pgXmplLed xmpl_leds.c - Using the LED Macros

 @section sexXmplLeds LED Macro Example
 @dontinclude "xmpl_leds.c"
 @skip Id
 @until EOF
*/

/**
 @page pgXmplKey xmpl_keys.c - Using the KEY Macros

 @section sexXmplKeys KEY Macro Example
 @dontinclude "xmpl_keys.c"
 @skip Id
 @until EOF
*/

/**
 @page pgXmplKeyEvents xmpl_key_events.c - Implementing Key Events

 @section sexXmplKeyEvents Key Event Example
 @dontinclude "xmpl_key_events.c"
 @skip Id
 @until EOF
*/


/**
 @page pgXmplTmr xmpl_timer.c - Using the Timer Macros

 @section sexXmplTimer Timer Macro Example

 @dontinclude "xmpl_timer.c"
 @skip Id
 @until EOF

 */

/**
 @page pgXmplHif xmpl_hif.c - Using the Host Interface Functions

 @section sexXmplHifLib Host Interface Library Example
 @dontinclude "xmpl_hif.c"
 @skip Id
 @until EOF

 @par Application Description

 The programm dumps at first a view text lines to the host interface, then
 waiting for input data. All characters received are echoed, except for
 '\\n' and '\\r' which where treated as line break, printing out a prompt with
 the current line number in square brackets.

 This is an example screenshot of the terminal window, with the output of
 tree command, redirected to the HIF.

 @image html scrn_xmpl_hif.png "Screenshot of terminal window." width=10cm

*/

/**
 @page pgXmplDbg xmpl_dbg.c - Using the Debug Pin Macros

 @section sexXmplDbgMacro Debug Pin Macros Example
 @dontinclude "xmpl_dbg.c"
 @skip Id
 @until EOF

*/

/**
 @page pgXmplTrxBase xmpl_trx_base.c - Using Basic Transceiver Access Functions

 This example illustrates the use of the basic radio transceiver
 access functions. It can be used to test a new board definition.

 @dontinclude "xmpl_trx_base.c"
 @skip Id
 @until EOF

 */

/**
 @page pgXmplTrxTx xmpl_trx_tx.c - Transmitting Frames

 The next example shows, how a frame is transmitted.

 @dontinclude "xmpl_trx_tx.c"
 @skip Id
 @until EOF

 */

/**
 @page pgXmplTrxRx xmpl_trx_rx.c - Receiving Frames

 This example shows, how frames are received and their CRCR16 is
 checked in software.

 @par Code Example

 @dontinclude "xmpl_trx_rx.c"
 @skip Id
 @until EOF

 */

/**
 @page pgXmplTrxEcho xmpl_trx_echo.c - Echo Frames

 This example shows, how frames are received and retransmitted
 if their CRC was correct.
 This example is esentially a combination from
 @ref pgXmplTrxTx and @ref pgXmplTrxRx. The retransmission of
 the frames is initiated within the transceiver interrupt routine
 without any CCA.

 @note Use this example with @b care !!! You can mess up your sensor
 network easily.

 @par Code Example

 @dontinclude "xmpl_trx_echo.c"
 @skip Id
 @until EOF

 */

/**
 @page pgXmplTrxTxAret xmpl_trx_txaret.c - Transmitting Frames with TX_ARET

 @par Application Description

 The example shows, how a frame is transmitted in TX_ARET mode.
 Within this mode, CCA is done automatically. Additionally the
 example illustrates, how the fram data can be directly manipulated
 in the SRAM (see IRQ service routine).

 @par Code Example

 @dontinclude "xmpl_trx_txaret.c"
 @skip Id
 @until EOF

 */

/**
 @page pgXmplTrxRxAack xmpl_trx_rxaack.c - Receiving Frames with RX_AACK

 @par Application Description

 @par Code Example

 @dontinclude "xmpl_trx_rxaack.c"
 @skip Id
 @until EOF

 */


/**
 @page pgXmplRadio Using the Radio Module

 The reference to the transceiver module can be found here:
  - @ref grpRadio

 The example below shows .....

 @code
#include "board.h"
#include "radio.h"
void main()
{
    radio_init(rxbuf, MAX_FRAME_SIZE);
    ...
}

 @endcode

 @underconstruction
*/


/**
 @page pgXmplRadioRange xmpl_radio_range.c - Simple Range Test Application

 @par Application Description

 This application sends periodically a test frame and
 is the rest of the time in receive mode. All parameters
 of the received frames (ED, LQI, sequence number) are printed
 to the host interface.

 The LEDs have the following meaning:
  - LED0 flashes and signalizes the transmission of a frame.
  - LED1 toggles with each received frame.

 @par Code Example

 @dontinclude "xmpl_radio_range.c"
 @skip Id
 @until EOF

*/


/**
 @page pgXmplLbufferTx xmpl_linbuf_tx.c - Using Linear Buffers for Data Transmission

 @par Application Description

 The application fills a piece of text as chunks in a linear buffer
 and sends it. The example illustrates

   - the initialization of a linear buffer (see @ref grpIoUtilBuffer),
   - the appending of characters as payload,
   - the prepending of a frame header prior the payload,
   - the extraction of data pointer and data size from the buffer.
   - reset of the buffer.

 @par Code Example

 @dontinclude "xmpl_linbuf_tx.c"
 @skip Id
 @until XEOF

 */

/**
 @page pgXmplLbufferRx xmpl_linbuf_rx.c - Using Linear Buffers for Data Reception

 @par Application Description


 @par Code Example

 @dontinclude "xmpl_linbuf_rx.c"
 @skip Id
 @until XEOF

 */

/**
 @page pgXmplRadioStream xmpl_radio_stream.c - Using Radio Stream Functions

 @par Application Description

 This example shows, how the avr-libc
 <a target="_" href="http://www.nongnu.org/avr-libc/user-manual/group__stdiodemo.html">stdio
 facilities</a> can be used to do a printf to the radio transceiver.
 The data printed to the transceiver can be watched on a terminal either with
 the wuart application or with @ref pgXmplLbufferRx "xmpl_linbuf_rx.c".

 @par Code Example

 @dontinclude "xmpl_radio_stream.c"
 @skip Id
 @until XEOF

 */


/**
 @page pgXmplAccSimple xmpl_lgee_acc_simple.c - Printing Accelerometer Values to the Radio

 @par Application Description


 @par Code Example

 @dontinclude "xmpl_lgee_acc_simple.c"
 @skip Id
 @until XEOF

 */
