/* 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: dev.dox,v 1.23 2009/12/25 17:43:42 awachtler Exp $ */

/**
 @page pgDevMain HOWTOs and FAQs

 This part of the @uracoli manual gives information
 about the build process,
 the tools are used,
 how to add new hardware to the project and
 explains how to deal with the USB drivers for some of the boards.

  - General Help
    - @subpage pgGstartMain
  - Software
    - @subpage pgToolChain
    - @subpage pgDirStruct
  - Hardware
    - @subpage pgDevProgDebug
    - @subpage pgNewHw
  - Misc
    - @subpage pgDevUSB
    - @subpage pgDevMisc
    - @subpage pgDevFAQ

*/

/**
 @page pgToolChain Tool Chain and Build Process

 @section tocToolChain Introduction

 @uracoli maintains a lot of different embedded plattforms which
 are different in terms of radio transceiver, micro controller and
 wiring of both components. In order to reduce the efforts in
 maintaining this many configurations, the build process is automated
 in order to reduce error prone (... and boring) manual maintenance
 of the build system.

 Therefore @uracoli comes not just with a bunch of *.aps or Makefiles.
 Most of the work is done with Python scripts and from the Scons build
 system. Since XML comes more and more in the focus of todays software
 development, a XSL Transform tool is needed too. The rest ot the
 tools are the standard compiler, firmware downloaders, debug tools
 and doumentation generators.


 - @subpage pgrequtools @n
    <em>This section gives a short motivation for each tool.</em>
 - @subpage pg1stbuild
    @n
    <em>Here is the run of the build system explained.</em>
 - @subpage pgDevCodeGen

*/

/**
 @page pgrequtools Tool Chain

 @par Overview

 Beside the standard tools for compiling and loading software
 for the defined radio boards, there are additional tools required
 to run the automatic build process. Which tools are used for which
 purpose is described in the next section.

 - @subpage pgToolChainOvr

 @par Installation Instructions

 The following steps describe the tool chain setup under different
 operating systems.

    - @subpage pgToolChainWin
    - @subpage pgToolChainLin
    - @subpage pgToolChainLinFromScratch

*/

/**

 @page pgToolChainOvr Required Tools

 @par Build System and Code Generation

 In order to keep track of the dependencies among the source files
 automatically, when compiling the project, the scons build system
 was choosen. This build system is written in Python, therefore
 the interpreter is installed here too.

  @anchor motpython
  -# @b Python (mandatory)@n
     http://www.python.org @n
     Python is used as the central scripting language in this
     project, therefore it is mandatory to install. It is primarily
     used for the scons build system, utility scripts and PC
     applications.
     Python is used in version 2.x, starting with version 2.4 the build
     is tested. Version 3.x is not yet supported.
  @anchor motscons
  -# @b Scons (mandatory)@n
     http://www.scons.org @n
     Scons is a Python based build sytem, similiar to make. Its
     main strengths are
     - the clean dependency managment, which is based on
       hash sums instead of timestamps,
     - the flexible extension with Python functions and
     - the easy to read and understand build scripts.
  @anchor motlibxml2
  -# @b libxml2 and @b libxslt (optional)@n
     http://www.xmlsoft.org/ @n
     This libraries from the Gnome project are used for transforming
     and validating XML files, e.g. AvrStudio .aps-project files.
     The @uracoli webpages are altough generated by XSL transformation
     from raw XML files. The packages should be installed, if the xmpl*.aps
     files have to be generated.

 @par AVR Tools

  For cross compiling the @uracoli sources the avr-gcc compiler and
  the avr-binutils are needed. The avr-libc package provides a standard
  C library for AVR micro controllers.

  @anchor motbinutils
  -# <b>GNU AVR Binutils</b> (mandatory)@n
     http://www.gnu.org/software/binutils @n
     This packages contain the assembler, linker
     and various utilities for generating and transforming
     executable programm code for AVR microcontrollers.
  @anchor motgcc
  -# <b>GNU AVR GCC</b> (mandatory)@n
     http://www.gnu.org/software/gcc @n
     The GNU compiler collection provides compilers for different
     programming languages. For this project the AVR GCC compiler
     is used.
  @anchor motavrlibc
  -# <b>AVR Libc</b> (mandatory)@n
     http://avr-libc.nongnu.org @n
     AVR Libc is collection of high quality C functions and
     macros to be used in conjunction with AVR microcontrollers.

 @par Programming and Debugging of Radio Boards

 For loading and debugging executables on radio boards, different
 tools for Linux and Windows are used.

  @anchor motprog
  -# @b Programmer (mandatory)
    - Linux/Unix: avrdude
    - Windows: AvrStudio
  @anchor motdeb
  -# @b Debugger (optional but highly recommended)
    - Linux/Unix: avarice, avr-gdb, ddd
    - Windows: AvrStudio

 @par Documentation

  The project documentation is generated as set of HTML files with doxygen.
  Additionally tool graphviz (dot) is needed to generate images of graphes.

  @anchor motdox
  -# <b>Doxygen</b> (optional)@n
     http://www.doxygen.org @n
     Doxygen is a documentation system for various programming
     languages, including C and Python. The tool should be installed,
     if the documentation has to be generated.
  @anchor motdot
  -# <b>Graphviz</b> (optional)@n
     http://www.graphviz.org @n
     Graphviz is a tool for visualization of dependency graphs and
     networks. It is mainly used inside the documentation for illustrating
     the relations of various programm components. The tool should be installed,
     if the documentation has to be generated.


 @par PC Applications

  Because of its platform independence, the PC applications
  of the @uracoli project are written in Python, which uses a few
  additional packages that are not part of the standard distribution.
  Additionally when developping more complex wireless applications
  a wireless sniffer tool makes the debugging process a lot easier.

  @anchor motpyser
  -# @b pyserial (optional)@n
     http://pyserial.sourceforge.net @n
     The pyserial package provides plattform independent access to
     serial interfaces of a PC. It is mandatory needed for any
     Python application that communicates via serial interface with
     an AVR microcontroller. The package should be installed, and has
     to be installed, if the packet capturing is used.
  @anchor motpyexe
  -# @b py2exe (optional, only windows)@n
     http://www.py2exe.org/ @n
     py2exe is a Python Distutils extension which converts Python
     scripts into executable Windows programs, able to run without
     requiring a Python installation.
     The package should be installed with windows esxecutables should
     be generated from python scripts.
  @anchor motwshark
  -# @b Wireshark (optional)@n
     http://www.wireshark.org/ @n
     In conjunction with the @uracoli packet capture tool, wireshark
     is used for decoding and displaying frames, captured on air.
     The package should be installed, and has to be installed, if the
     packet capturing is used.

 @par Source Code Managment

 This tools are used if you want to check in and check out
 the @uracoli source code directly from the CVS repository.

  @anchor motcvs
   -# @b CVS (optional but highly recommended)@n
      http://cvs.nongnu.org @n
      The cvs tool (Concurrent Versions System) is needed for checking
      out, comparing and committing files from and to the source code repository.
      The tool is needed to update the local @uracoli project tree from
      the repository. Since the project changes rapidly in this development
      phase, the tool is highly recommended to be installed.
  @anchor motssh
   -# @b ssh and @b ssh-agent (optional)@n
      http://www.openssh.com/ @n
      The secure shell is needed for accessing the repository
      as registered @uracoli developer. All other people interested
      in the project, will be able to do an anonymous checkout via
      the pserver protocol.

 */

/**
 @page pg1stbuild Building @uracoli

 In order to build the project or subproject, scons is used in
 the following way.

 @par Help

  - <tt>scons -h</tt> @n
    display a screen with the current options of the build system

 @par Building

   - @c scons or <tt>scons all</tt> @n
       build libraries and applications for all plattforms
   - <tt>scons doc</tt> @n
      build documentation
   - <tt>scons libs</tt> @n
      build libraries for all plattforms
   - <tt>scons apps</tt> @n
      build applications for all plattforms
   - <tt>scons &lt;BoardType&gt;</tt> @n
       build libraries and applications for specified board type:
      - <tt>&lt;BoardType&gt;</tt>: stkm16, ict230, ...
   - <tt>scons l&lt;BoardType&gt;</tt> @n
       build libraries for specified board type
   - <tt>scons a&lt;BoardType&gt;</tt> @n
       build applications for specified board type
   - <tt>scons x&lt;BoardType&gt;</tt> @n
       build example applications for specified board type

 @par Cleaning

   - <tt>scons -c &lt;target&gt;</tt> @n
      cleaning a specific target
      - <tt>&lt;target&gt;</tt> @n
         all, doc, libs, apps, &lt;BoardType&gt;, l&lt;BoardType&gt;, a&lt;BoardType&gt;
   - <tt>scons -c distclean</tt> @n
       remove all created files and directories

*/

/**
 @page pgDevProgDebug Programming and Debugging Targets

 @section secDevProg Programming with avrdude

 @note  avrdude uses libusb to access JTAG-ICE, Dragon, ISP etc. 
        Section @ref pgDevUSBPROG describes, what to do, that 
        normal users can access these devices.

 @code
  (1)  avrdude -P usb -p m1281 -c jtag2 -U fl:w:install/bin/sniffer_stk541.hex
  (2)  avrdude -P usb:4711 -p m1281 -c jtag2 -U fl:w:install/bin/sniffer_stk541.hex
  (3)  avrdude -P usb:1234 -p m1281 -c avrisp2 -U fl:w:install/bin/sniffer_stk541.hex
 @endcode


 @section secDevDebug Debugging with avarice + avr-gdb (ddd)

 @code
   avarice -I -P atmega1281 -2 -j usb --detach :4242
   ddd --debugger avr-gdb install/bin/sniffer_stk541.elf &
 @endcode

 When ddd/avr-gdb has opened, type @c "target remote:4242<ENTER>"
 in order to connect avarice and avr-gdb.

 
 

 @section secDevDW Using DebugWire

 @par Enable DebugWire

 @todo finish this section, it is incomplete not fully tested.

 - use any isp capable programmer: stk500v2, jtag2isp, dragon_isp??
 @code

    ISPDUDE="-c jtag2isp -P usb -p t44"
    DWDUDE="-c jtag2dw -P usb -p t44"
    avrdude $ISPDUDE  -F -U hfuse:w:????:m
    avrdude $DWDUDE -F
 @endcode

http://www.homebuilthardware.com/index.php/avr/linux-avrdragon-tutorial-1/
*/

/**
@page pgNewHw How to add a new radio board to the library


The following section illustrates how to add your own
radio board to the @uracoli build process, For illustration of
the steps, the board tiny230 from DL8DTL is used.

@par Create two board identifiers.

Select a short and a long name for the board.

The short name should contain 4 ... 8 lower case letters and numbers, e.g.
@e tiny230.
It is used for naming the board in the scons build process
(<tt>scons tiny230</tt>) and identifying the generated libraries and
executables (<tt>ls install/*/*_tiny230.*</tt>).

The long name should contain 12 ... 16 upper case letters and numbers and
underlines, e.g. @e TINY_230.
It is used as symbolic name for a unique board identifier, defined in
Src/Lib/Inc/const.h.

@par Create a board abstraction header file

The board abstraction header file (e.g. Src/Lib/Inc/boards/board_tiny230.h)
defines macros for accessing the ressources of the radio board, such as SPI
and GPIO pins.

The board abstraction header files are located in the directory @em Src/Lib/Inc/boards.

Before you start to write your own board abstraction file from scratch, have a
look into the already existing files. Either you copy one of the existing files
and modify it or you simply add an alias to an existing board. See @e board_rbb.h
for an example, how the aliases rbb230, rbb231 and rbb212 are handled.

The alias method should always used, if the boards belongs to the same family
and are rebuilds/clones of existing ones, but should have a new name.


@par Modify const.h

Add the @e long @e name to the file @em Src/Lib/Inc/const.h
and give it a unique number.

@todo Check to use an enum instead of a define in order to
      avoid non uniqeness of the assigned numbers.

@code
Src/Lib/Inc/const.h #define  ZGB_LINK_231    (51) /**< Board description see @ref grpZgbLink . */
Src/Lib/Inc/const.h #define  ZGB_LINK_212    (52) /**< Board description see @ref grpZgbLink . */
Src/Lib/Inc/const.h
Src/Lib/Inc/const.h /* DIY and wirewrap projects */
Src/Lib/Inc/const.h #define  TINY_230        (90) /**< Board description see @ref grpTINY230 . */
Src/Lib/Inc/const.h #define  STK500_MEGA8    (91) /**< Board description see @ref grpSTKM8 . */
Src/Lib/Inc/const.h #define  STK500_MEGA16   (92) /**< Board description see @ref grpSTKM16 . */
@endcode


If your newly added radio board uses a MCU, that is not yet used, you
also need to add a unique define


@par Add the board to the file board.cfg

Add a configruation section to Src/Lib/Inc/boards/board.cfg.

@code
# Joergs low resource DIY board with ATtiny84.
[tiny230]
aliases    = tiny231
comment    = Joerg's (DL8DTL) ATtiny44 with AT86RF230
include    = boards/board_tiny230.h
cpu        = attiny84
bootoffset = 0x0
ccflags    =
f_cpu      = 8000000UL
no_app     = diag rdiag wuart wuart2 sniffer
no_xmpl    = xmpl_keys xmpl_key_events xmpl_hif xmpl_hif_echo
             xmpl_radio_stream
@endcode


@param [sectionname]
       This is name of the board, it must be a unique
       among all board and alias names.
@param aliases
       A space seperated list of aliased derivates of this
       board
@param comment
       The comment is displayed when <tt>scons -h</tt> is used.
@param include
       Name of the board abstraction header file.
@param cpu
       MCU name which is  used in mmcu option of avr-gcc.
@param bootoffset
       Location address of the boot loader.
@param ccflags
       Additional compiler parameters, like -I or -D options.
@param f_cpu
       MCU clock frequency
@param no_app
       @uracoli applications that should be excluded from the build,
       e.g. due to the lack of ressources.
@param no_xmpl
       @uracoli examples that should be excluded from the build,
       e.g. due to the lack of ressources.
@param more_xmpls
        board specific example applications.

@par Build the software of the new radio board

@code
scons install\inc\board_cfg.h
scons tiny230
@endcode

<div style="color:grey">
@subsection secCreateXbrd32h Create a board definition header file
 - copy board_dummy.h to board_xbrdm32.h
   - fill wiring comment
   - replace include guards BOARD_DUMMY_H with BOARD_XBRDM32_H
   - fill CPU_TYPE (see const.h, if necessarry add your cpu there)
   - fill all "..." placeholder according your wiring
   - for impl. of the Macros TRX_IRQ_INIT, DI_TRX_IRQ,EI_TRX_IRQ
     consult the CPU data sheet
   - in necessary adapt the inline function SPI_INIT
   - implement LED_SET_VALUE and LED_GET_VALUE in order
     to reflect if your LED's react inverted (STK500) or not.
   - TUNED_OSCCAL is necessarry if your CPU uses the internal
     RC Oscilator and runs at different voltage level then
     during the factory calibration of your CPU. Use the
     calosc.c application in order to check this.
     Tuning the OSCCAL register is only needed, if you need
     a correct uart baud rate.
</div>

*/

/** @page pgDirStruct File and Directory Structure of the Package

   After unpacking the archive file, you'll find the following
   directory structure.

   <pre>
uracoli
|
+---Src ............................. Sources
|   +---Lib ......................... Library source code
|   |   +---Inc
|   |   |   \---boards
|   |   +---Ioutil
|   |   \---Rf230
|   +---App ......................... Application source code
|   |   +---Inc
|   |   \---Sniffer
|   \---Xmpl ........................ Example source code
|
+---Contrib ......................... PC Applications, that interact
|                                     with firmware applications
|   \---PacketCapture ............... Sniffer Interface
|
+---Doc ............................. Doxygen Sources
|   +---App
|   +---Contrib
|   +---Dev
|   +---Images
|   \---Usr
|
+---Templates
|
+---Tools
|
| +-------------------------------------------------------------------------+
| | directories below here can be erased, they are generated while building |
| +-------------------------------------------------------------------------+
|
+---build ........................... temporary build directories
|
\---install ......................... compiled/generated files
    +---bin ......................... elf/hex files
    +---doc ......................... html doc
    |   +---app
    |   +---contrib
    |   +---dev
    |   \---usr
    +---inc ......................... include files, interface for the libs
    |   \---boards
    +---lib ......................... static libraries
    \---xmpl ........................ all example, make- and project files
</pre>

*/

/**
@page pgDevCodeGen Automatic Code Generation

Some of the source files are created by code generation scripts. The following picture
shows the dependencies between the templates and the generated source files.

@dot
  digraph "g" {
      graph [rankdir="LR",size="14,14"];
      bgcolor="transparent";
      node [shape = "record"];

      "board.cfg" -> "boardcfg.py" -> "board_cfg.h";

      "board_cfg.h" -> "board.h|...\n#include \"board_cfg.h\"";

      "at86rfXXX.txt" -> "ds2reg.py" -> "at86rfXXX.h";

      "at86rfXXX.h" -> "transceiver.h|...\n#include \"at86rfXXX.h\"";


   }
@enddot



*/


/**
 @page pgDevMisc Random Notes

 @section secImgCols Color Codes used for Images

<pre>
 Group          Open Office Codes           HTML
----------------------------------------------------
 uracoli logo  230 230 255 (Blue Gray)      \#e6e6ff
 radio         230 230 255 (Blue Gray)      \#e6e6ff
 background    247 250 247 (uracoli green)  \#f7faf7
 transceiver   204 204 255 (Sun 4)          \#ccccff
 board         230 230 230 (Gray 10%)       \#e6e6e6
 timer         255 204 153 (Orange 4)       \#ffcc99
 hif           255 128 128 (Salmon)         \#ff8080
 ioutil        230 230  76 (Yellow 4)       \#e6e64c
 # free colors
               153 204 255 (Blue 8)         \#99ccff
               255 255 204 (Pale Yellow)    \#ffffcc
</pre>

 @section secIncLayout Current Include File Layout

 \dotfile "radio.dot" "Include file graph for libradio_<board>.a"

 \dotfile "ioutil.dot" "Include file graph for libioutil_<board>.a"


 */

/**
 @page pgDevUSB USB drivers
   - @subpage pgDevFTDI245
   - @subpage pgDevCDC
   - @subpage pgDevUSBPROG
 */

/**
 @page pgDevFTDI245 FT245BM Driver

 The FTDI FT245BM is a FIFO to USB converter with a
 parallel interface.
 The USB device emulates a serial port, which is COMx in
 Windows or /dev/ttyUSBx in Linux
 (http://www.ftdichip.com/FTProducts.htm#FT245BM).

 With the parallel interface its easy to provide a high data
 rate connection between PC and AVR. The memory buffer
 inside the FT245xx for both, TX and RX direction,
 relaxes the CPU load on the AVR side. The MCU can write/read
 whole chunks of data to the chip without lots of interrupts
 or peramnently polling a USART status register.

 The FT245 can be branded with custom vendor and product IDs
 in a external EEPROM. In combination with the hardware described
 here, the following combinations can occur:

   - original FT245BM ID
     - Vendor 0x0403, Device 0x6001
   - Atmel STK541 Sniffer Kit
     - Vendor 0x03eb, Device 0x2009
     - http://www.nongnu.org/uracoli/hwlist.html#STK541
   - Dresden Electronic Sensor Terminal Board
     - Vendor 0x1cf1, Device 0x0001
     - http://www.nongnu.org/uracoli/hwlist.html#STB230

 The following sections describe, how the driver for
 different VID/PID in Linux and Windows is adapted:

   - @subpage pgDevFTDI245Linux
   - @subpage pgDevFTDI245Windows
*/
/**
 @page pgDevFTDI245Linux  Patching the FT245 Driver under Linux

 This steps have to be done in order to modify the Linux kernel
 module @c ftdi_sio.ko so, that it accepts devices with the vendor/device
 IDs of the Atmel STK541 and/or the Dresden Elektronik Sensor Terminal Board
 and assigns them a serial device like @c /dev/ttyUSBxx.


 @par Modify the Driver Source Code
 In the directory @c /usr/src/linux/drivers/usb/serial/ there are the
 files @c ftdi_sio.h and @c ftdi_sio.c, which needs to be modified.

 There are two patches available but most probably they will not work at
 a specific system, since in @c ftdi_sio.c, the line numbers change rapidly by adding new
 devices from other vendors. So the patches most probably needs to be applied manually.

  - <a href="ftdi_sio_2.6.13-15-default.patch">ftdi_sio_2.6.13-15-default.patch</a>  (SuSE 10.0, default kernel)
  - <a href="ftdi_sio_2.6.25.5-1.1-pae.patch">ftdi_sio_2.6.25.5-1.1-pae.patch</a>  (SuSE 11.0, default kernel)

 At first, the macros for the vendor and product ID
 of the boards have to be added in the file @c ftdi_sio.h:329.

 @code
    #define ATMEL_VID              0x03eb  /* Atmel Vendor ID */
    #define STK541_PID             0x2109  /* Zigbee Controller */
    #define DE_VID                 0x1cf1  /* Dresden Electronic Vendor ID */
    #define STB_PID                0x0001  /* Sensor Terminal Board */
 @endcode

 Next in the file @c ftdi_sio.c the new Vendor/Device ID tuples needs to be added:

 @code
     static struct usb_device_id id_table_combined [] = {
            { USB_DEVICE(FTDI_VID, FTDI_AMC232_PID) },
            ...
            ...
            ...
            { USB_DEVICE(ATMEL_VID, STK541_PID) },
            { USB_DEVICE(DE_VID, STB_PID) },
            { },                                    /* Optional parameter entry */
            { }                                     /* Terminating entry */
     };
 @endcode


 @par Build the Modified Kernel Modul

 <pre>
    root\@pandora>cd /usr/src/linux
    root\@pandora>make drivers/usb/serial/ftdi_sio.ko
    CC [M]  drivers/usb/serial/ftdi_sio.o
    MODPOST
    CC      drivers/usb/serial/ftdi_sio.mod.o
    LD [M]  drivers/usb/serial/ftdi_sio.ko
 </pre>

 @note
 If an error message like "You have not yet configured your kernel! (missing kernel .config file)" occurs,
 under SuSE Linux you can quickly recover from this issue by doing "zcat /proc/config.gz > .config"
 in the directory @c /usr/src/linux.

 @par Install the new Kernel Modul

 <pre>
    root\@pandora>rmmod ftdi_sio
    root\@pandora>cd /lib/modules/`uname -r`/kernel/drivers/usb/serial
    root\@pandora>cp ftdi_sio.ko ftdi_sio.ko.orig
    root\@pandora>cp /usr/src/linux/drivers/usb/serial/ftdi_sio.ko .
    root\@pandora>depmod -a
 </pre>

 @par Load and Test the new Kernel Modul

 <pre>
    root\@pandora>modprobe ftdi_sio
    root\@pandora>lsmod | grep ftdi
    ftdi_sio               27400  0
    usbserial              28776  1 ftdi_sio
    usbcore               112640  5 ftdi_sio,usbserial,uhci_hcd,rt73
    root\@pandora>dmesg | grep FTDI
    ftdi_sio 1-1.2:1.0: FTDI USB Serial Device converter detected
    usb 1-1.2: FTDI USB Serial Device converter now attached to ttyUSB0
    drivers/usb/serial/ftdi_sio.c: v1.4.3:USB FTDI Serial Converters Driver
 </pre>

*/

/**
 @page pgDevFTDI245Windows  Using the FT245 Driver under Windows

 @section secFTDIInstall Installation
 In order to operate the sensor terminal board or STK541 under
 windows, the virtual COM port driver (VCP) from http://www.ftdichip.com/Drivers/VCP.htm
 has to be used.
 With the following steps the driver gets installed:

 -# Download the driver package @e "CDM 2.04.06 WHQL Certified.zip"
 -# Unpack it in a temp directory.
 -# Apply the patch <a href="ftdi_cdm_2.04.06.patch">ftdi_cdm_2.04.06.patch</a>
    manually or with the @e patch command (e.g., if mingw or cygwin is installed).
 -# Connect the USB board to the PC and guide the hardware assistent to
    the patched directory and complete the installation. Since the WHQL
    certification breaks with the patch, you have explicitely to confirm,
    that you want to install @e that driver.
 -# Now you should find the assigned COM port in the device manager.

 @section secFTDIPatch Patch for ftdibus.inf and ftdiport.inf
 @include ftdi_cdm_2.04.06.patch

 @section secFTDILic VCP Driver Licensing Conditions

 The Website of FTDI states
 http://www.ftdichip.com/Drivers/VCP.htm (2009-02-03).

 <em><b>
 FTDI device drivers may be used only in conjunction with
 products based on FTDI parts.
 <br>
 The driver may be distributed in any form as long as our license information is not modified.
 <br>
 If a custom Vendor ID and/or Product ID, or description string are used, it is the responsibility of the product manufacturer to maintain any changes and subsequent WHQL re-certification as a result of using these changes.
 </b></em>


*/

/**
 @page pgDevCDC  Using the CDC driver for RZUSBSTICK

 The HIF driver for the Raven USB stick implements a CDC device.
 This can be handled by generic virtuell COM port driver.

 The Vendor/Device ID used by @uracoli is:

  - Vendor ID: 5824 0x16C0
  - Product ID: 2183 0x887

 see also http://www.frank-buss.de/pid.txt

 @par Linux

 - /usr/sbin/lsusb\n
   - <tt>Bus 003 Device 009: ID 16c0:0887</tt>
 - for SuSE 10.0 the driver cdc_acm was not loaded automatically,
   in this case the command "modprobe cdc_acm" loads the driver.
 - dmesg | grep ACM ==> "cdc_acm 3-1.4:1.0: ttyACM0: USB ACM device"
 - Some older pyserial versions come up with the following error:
   <tt>[Errno 11] Resource temporarily unavailable</tt>
   In this case apply the patch or upgrade pyserial:
   http://mail.python.org/pipermail/python-list/2004-November/294242.html

 @par Windows

 - @uracoli provids a INF file that installs the usbserial.sys driver.
   <a href="uracoli-cdc.inf">uracoli-cdc.inf</a>
   @include uracoli-cdc.inf



*/


/**
 @page pgDevUSBPROG Using USB connected Programmers under Linux
 
 @par SuSE 11.0
 
 @code 
 cd  /etc/udev/rules.d/80-usbprog.rules
 vi 80-usbprog.rules
 @endcode 
 
 In this file add the following lines:
 @code
 # AVR ISP
 ATTR{idVendor}=="03eb", ATTR{idProduct}=="2104", GROUP="users", MODE="0660"
 # AVR Dragon
 ATTR{idVendor}=="03eb", ATTR{idProduct}=="2107", GROUP="users", MODE="0660"
 # JTAG ICE MkII
 ATTR{idVendor}=="03eb", ATTR{idProduct}=="2103", GROUP="users", MODE="0660"
 @endcode
 
 If you want to enable other USB devices for users access, just 
 check the output of lsusb command.
 
 @code
 $$ lsusb
  ...
  Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
  Bus 002 Device 009: ID 03eb:2103 Atmel Corp. JTAG ICE mkII
  Bus 002 Device 003: ID 07d1:3c03 D-Link System DWL-G122 802.11g Adapter [ralink rt73]
  Bus 002 Device 002: ID 0409:005a NEC Corp. HighSpeed Hub
  ...
 @endcode
 
 Thanks to the german description at: 
 http://www.wiki.elektronik-projekt.de/mikrocontroller/avr/avrdude

 @par SuSE 10.0
 
 Add the following line at the end of file  
 /etc/udev/rules.d/50-udev.rules

 @code
 SUBSYSTEM=="usb", ACTION=="add", ENV{PRODUCT}=="3eb/2103/*", RUN+="/bin/sh -c '/bin/chgrp uucp $env{DEVICE} ; /bin/chmod g+w $env{DEVICE}'"
 @endcode

*/


/**
 @page pgDevFAQ FAQs

 A FAQ collection will come up here,


*/
