/* Copyright (c) 2010 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: arduino.dox,v 1.4 2010/12/22 21:51:09 awachtler Exp $ */

/**
\if ARDUINODOC
 @mainpage Arduino Support Package

 This pages describe how the Arduino Environment is used together
 with the libraries of the @uracoli project.

 - @subpage pgContribArduino
 - @ref HardwareRadio
 - @subpage pgArduinoLicense

\endif

 @page pgContribArduino Running Arduino with RadioFaro and ZigDuino Boards.

 @section secArduinoOverview Overview

 <a href="http://arduino.cc/">Arduino</a> is a Microcontroller Development
 plattform that consists of a Java-IDE and different microcontroller
 boards. All of the supported boards are equipped mit AVR-8-bit-MCUs.
 Basically the Arduino IDE provides an integrated editor, a serial terminal
 and buttons to compile and upload the firmware to the MCU.

 In order to keep things very simple for beginners and none technicians,
 the nitty gritty details of microcontroller programming (ports, registers,
 interrupts) are buried in the Arduino core library. Therefor the user is
 faced with a simplistic API that is described <a href="http://arduino.cc/en/Reference/HomePage">here</a>.

 The user writes its own applications in the Arduino IDE in form of
 sketches. A sketch basically implements two functions setup() and
 loop() that are called from the main() function of the core library.

 @uracoli provides a third party core file package for Arduino, that supports the boards
 @ref secBoardfunkomat "RadioFaro" and @ref secBoardzigduino "Zigduino".
 This core contains the
 <a href="http://arduino.cc/en/Reference/HomePage">standard Arduino functions</a>
 and the @uracoli radio functions.

 @image html radiofaro_low.jpg "RadioFaro board" width=90%

 Both boards are equipped with a ATMega128RFA1, which has an integrated
 2.4 GHz transceiver.

 @section secArduinoGStart Getting Started

 Currently (as of version 0021) the Arduino Toolchain is quite mature and
 does not support newer MCUs like the Atmega128RFA1. Therefore an upgrade
 of the Arduino Toolchain is needed.

 In order to do this, install the modified Arduino package from
 http://download.savannah.gnu.org/releases/uracoli/Arduino/.
    - MAC OSX: Arduino-0021-crosspack20100115.zip   (80M)
    - Windows w/o Java: Arduino-0021-uracoli-expert.zip (82M)
    - Windows w/ Java:  arduino-0021-uracoli.zip (121M)
    - Linux: arduino-0021-uracoli.tgz   (3.7M)

 For more advanced users it is sufficient if you solely upgrade the
 toolchain of your current Arduino install
    - MAC OSX: update crosspack
    - Windows:
    - Linux: arduino-0021-uracoli.tgz   (3.7M)

 In the next step you need to download the package uracoli-arduino-[version].zip
 and unpack it in your private sketchbook folder.

 After unpacking the package you'll find the following directory structure:
    <pre>
            sketchbook/
            |-- examples
            |   |-- HelloRadio
            |   |-- IoRadio
            |   `-- RadioUart
            |-- hardware
                `-- uracoli
                    |-- bootloaders
                    |   `-- radiofaro
                    `-- cores
                        `-- radiofaro
                            `-- boards
    </pre>

  Now you are ready to go and launch the the Arduino IDE,
  connect one of the above boards and try the example sketches.


 @section secArduinoRef Function Reference

 Beside the normal core functions (see http://arduino.cc/en/Reference/HomePage)
 there are some radio specific functions, described here @ref grpContribArduino.


 @section secArduinoSketches Example Sketches

 @par Sending Strings
 @includelineno HelloRadio/HelloRadio.pde
 @includelineno IoRadio/IoRadio.pde
 @includelineno RadioUart/RadioUart.pde
 */


/**
 \ifnot ARDUINODOC
  @ingroup grpApp
 \endif

  @defgroup grpContribArduino Arduino Radio Functions

  This is the docmentation of the Arduino contribution functions.

  @file HardwareRadio.h
  @ingroup grpContribArduino


 */

/**

 \if ARDUINODOC

 @page pgArduinoLicense Arduino Support Package License and Copyright

The files in this package are underlying a dual licensing scheme,
comined of LGPL and modified BSD License. Both licenses are compatible
and does not exclude each other.

That code in our source tree which falls under the Library General Public License (LGPL)
comes with slightly more strings attached, rather then the software submitted under the
more relaxed modified BSD copyright.

All original and modified Arduino core files are licensed according the Arduino project
under the LGPL license, see also http://arduino.cc/en/Main/FAQ. The files are:

 - uracoli/cores/radiofaro/binary.h
 - uracoli/cores/radiofaro/HardwareSerial.cpp
 - uracoli/cores/radiofaro/HardwareSerial.h
 - uracoli/cores/radiofaro/main.cpp
 - uracoli/cores/radiofaro/Makefile
 - uracoli/cores/radiofaro/Print.cpp
 - uracoli/cores/radiofaro/Print.h
 - uracoli/cores/radiofaro/PureVirtual.cpp
 - uracoli/cores/radiofaro/Stream.h
 - uracoli/cores/radiofaro/Tone.cpp
 - uracoli/cores/radiofaro/WConstants.h
 - uracoli/cores/radiofaro/WInterrupts.c
 - uracoli/cores/radiofaro/wiring_analog.c
 - uracoli/cores/radiofaro/wiring.c
 - uracoli/cores/radiofaro/wiring_digital.c
 - uracoli/cores/radiofaro/wiring.h
 - uracoli/cores/radiofaro/wiring_private.h
 - uracoli/cores/radiofaro/wiring_pulse.c
 - uracoli/cores/radiofaro/wiring_shift.c
 - uracoli/cores/radiofaro/WMath.cpp
 - uracoli/cores/radiofaro/WProgram.h
 - uracoli/cores/radiofaro/WString.cpp
 - uracoli/cores/radiofaro/WString.h
 - uracoli/bootloaders/radiofaro/ATmegaBOOT.c


All @uracoli files and the related documentation is released
under the terms of the Modified BSD License.

 - uracoli/cores/radiofaro/atmega_rfa1.h
 - uracoli/cores/radiofaro/board_cfg.h
 - uracoli/cores/radiofaro/board.h
 - uracoli/cores/radiofaro/boards/board_derfa.h
 - uracoli/cores/radiofaro/const.h
 - uracoli/cores/radiofaro/HardwareRadio.cpp
 - uracoli/cores/radiofaro/HardwareRadio.h
 - uracoli/cores/radiofaro/pins_rfarduino.c
 - uracoli/cores/radiofaro/pins_uracoli.h
 - uracoli/cores/radiofaro/radio.h
 - uracoli/cores/radiofaro/radio_rfa.c
 - uracoli/cores/radiofaro/sketch.tpl
 - uracoli/cores/radiofaro/transceiver.h
 - uracoli/cores/radiofaro/trx_datarate.c
 - uracoli/cores/radiofaro/trx_datarate_str.c
 - uracoli/cores/radiofaro/trx_rfa.c
 - uracoli/cores/radiofaro/usr_radio_irq.c

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

 \endif
 */

/*
 @page pgContribArduino  Arduino Support

 This section describes how to use Zigbit modules in the Arduino Build Environment.
 Currently the build process is described for Linux.


 @section secArduinoFromScratch Build the Arduino Environment from the Sources.

 @par Get Arduino Sources

 @code
 svn checkout http://arduino.googlecode.com/svn/trunk/ arduino  && echo OK
 @endcode

 The checkout may need several retries, since connection maybe reset during
 checkout. If you see "OK" on the command line, then svn has succeeded.
 (Normally you will need 2 to 5 retries, depending how often the svn server
 cancels the the connection).

 @note
 In order to save the time of a complete check out for later updates,
 zip the build directory now.

 @par Prebuild the distribution

 The next step patches some source files and builds the distribution.

 @code
 cd arduino/
 patch -p0 -i [uracoli-src-dir]/Contrib/Arduino/zigbit.patch
 cd build/linux
 bash make.sh
 @endcode

 The make.sh script produces this output:

 @code
 Setting up directories to build for Linux...
 cp: cannot stat `../shared/libraries': No such file or directory
 Copying examples...
 Extracting reference...
 Extracting JRE...
 Building processing.core
 Note: Some input files use unchecked or unsafe operations.
 Note: Recompile with -Xlint:unchecked for details.

 Done.
 @endcode

 While running make.sh, it seems that the following error message
 can be ignored.
 <pre>
 cp: cannot stat `../shared/libraries': No such file or directory
 </pre>

 @par Build your personal Zigbit Arduino Distribution

 @code
 cd arduino/build/linux
 cp -rfv [uracoli-src-dir]/Contrib/Arduino/examples/* ../shared/examples/
 cp -rfv [uracoli-src-dir]/Contrib/Arduino/hardware/* ../../hardware/
 bash dist.sh
 @endcode

 The dist.sh script produces this output:


 @code
  Creating Arduino distribution for revision 0018...
  Building processing.core
  Note: Some input files use unchecked or unsafe operations.
  Note: Recompile with -Xlint:unchecked for details.

  Done.
  cp: cannot stat `../shared/libraries': No such file or directory
  Copying examples...
  Extracting reference...
  Creating tarball and finishing...
  Done.
 @endcode


 @par Install and Test the new distribution

 The result file is arduino-<version>.tgz, unpack it and start arduino in
 the usual way.

 Copy arduino-<version>.tgz to a save place and remove the arduino directory.

 @code
 tar xvzf arduino-<version>.tgz
 cd arduino-<version>
 ./arduino
 @endcode


@section secArduinoPatch Patch arduino binary distribution

 @todo Check if it would be possible to replace the patched Compiler.java
 in the jar archiv, so only this file needs to be checked out.
 (see arduino/build/linux/work/lib/pde.jar that contains arduino/app/src/processing/app/debug/Compiler.class)


*/
