/* 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: packetcapture.dox,v 1.11 2009/03/18 22:02:47 awachtler Exp $ */


/**
 @page pgContribCapture 802.15.4 Packet Capturing with Wireshark

 This @uracoli contribution describes, how the traffic on a
 IEEE 802.15.4 wireless sensor network can monitored.
 Therefore the sniffer firmware (see @ref grpAppSniffer)
 and the program wireshark/tshark are used. The connection
 between the serial interface of the PC and wireshark is
 realized with the small python application ieee802154.py.

  - @subpage pgCCULinux
  - @subpage pgCCUWindows
  - @subpage pgCCUCap
  - @subpage pgContribCaptureDev
*/

/**

 @page pgCCULinux Setup on Linux

 (@ref pgContribCapture "back")

 -# download the @uracoli source package and unpack it
 -# change to the to top directory<br>
     <tt>cd ~/src/uracoli-ZZZ</tt>
 -# build the sniffer application<br>
    <tt>scons a[PLF]</tt><br>
    @c [PLF] is the name of your target plattform (see @c "scons help")
 -# program your target plattform with the application @c "sniffer_[PLF].hex"<br>
    <tt>avrdude -P usb -pm1281 -c jtag2fast -U fl:w:install/bin/sniffer_stk541.hex</tt>
 -# verify, that the fuses of the MCU match the
    predfined values in @ref grpBoard.
 -# start wireshark<br>
    <tt>wireshark -i foo &</tt>
 -# start the application ieee802154.py<br>
    <tt>python Contrib/PacketCapture/ieee802154.py -p /dev/ttyUSB0 -i foo</tt>
 -# if erything worked well until here, you will see in the terminal:
    @code
uracoli sniffer to wireshark bridge V0.1.0
 OPTS:   -v -p /dev/ttyUSB0 -i foo
 INPUT:  /dev/ttyUSB0, channel: 15
 OUTPUT: foo

+ waiting for somebody to open the pipe
    @endcode
 -# in wireshark select "Capture -> Start" from the menu of The background of wireshark
    turns white.
 -# in the ieee802154.py terminal type @c "chan X", to select the channel you want to watch.
 -# .... now start sending packages in your WSN

 @image html wireshark-linux.png "Screenshot wireshark life capture." width=10cm
*/

/**
 @page pgCCUWindows Setup on Windows

 (@ref pgContribCapture "back")

 -# download the @uracoli source package and unpack it
 -# open a command shell window with @c cmd.exe
 -# change to the to top directory<br>
     <tt>cd /d z:/mysrc/uracoli-ZZZ</tt>
 -# build the sniffer application<br>
    <tt>scons a[PLF]</tt><br>
    @c [PLF] is the name of your target plattform (see @c "scons help")
 -# program your target plattform with the application @c "sniffer_[PLF].hex",
    e.g. with AvrStudio
 -# verify, that the fuses of the MCU match the
    predfined values in @ref grpBoard.
 -# start wireshark<br>
 -# enter the interface name <tt>\\\\.\\pipe\\foo</tt> as life capture interface.
 -# start the application ieee802154.py<br>
    <tt>python Contrib/PacketCapture/ieee802154.py -p COM12 -i foo</tt>
 -# if erything worked well until here, you will see in the cmd shell window:
    @code
uracoli sniffer to wireshark bridge V0.1.0
 OPTS:   -v -p /dev/ttyUSB0 -i foo
 INPUT:  COM12, channel: 15
 OUTPUT: foo

+ waiting for somebody to open the pipe
    @endcode
 -# in wireshark select "Capture -> Start" from the menu of The background of wireshark
    turns white.
 -# in the command shell window type @c "chan X", to select the channel you want to watch.
 -# .... now start sending packages in your WSN

 */

/**
 @page pgContribCaptureDev Technical Background

 (@ref pgContribCapture "back")

 In order to enable libpcap and wireshark to capture frames
 from an embedded application that connects via a serial RS232 or
 USB port to the PC, the following setup is needed

 <pre class="fragment">
 ((o))
   |
   +-[HwPlattform]--SerIf--+--[ieee802154.py]--WsPipe--[libpcap/*shark]
                    (-p)   |                       (-i)
                           |
     [PcapFile]----FileIo--+
                    (-r)
 </pre>

 The python script ieee802154.py provides a interconnection between a
 serial interface @c SerIf or a capture file @c PcapFile (in pcap file format)
 and a named pipe @c WsPipe, which is used as a live capture interface from
 wireshark/tshark.

 On the MCU the @ref grpAppSniffer "sniffer firmware"
 is installed. @note The serial interface needs to be sufficient fast in order to
 transfer all received frames over @c SerIf.  The interface has to be able to handle
 a data rate of 250kbit/s, which is the brutto data rate for the 2.4GHz radio transceivers.
 Therefore boards like @ref grpSTK541 "STK541" and @ref grpSTB230 with the parallel USB interfaces (e.g. with FT245 from FTDI Chip Inc.)
 ()
 are most suitable.

 In order to capture packets from a embedded device or a capture file, at first
 the script ieee802154.py is started. In the next step one of the capture
 tools, i.e. tshark, dumpcap or wireshark is attached  to the socket.
 The packets that now arrive at the serial interface or read from the capture
 file are forwarded to the socket and will be processed by the selected tool.

 @note Only one capture tool can be connected at a time to ieee802154.py.

*/
/**
    @defgroup grpContribCapture capture interface
    @brief Code documentation for capture interface.

 */
