/* 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$ */

/**
 \if SNIFFERPACKAGE
     @mainpage 802.15.4 Packet Capturing with Wireshark
 \elseif NEWDOC
     @defgroup grpSnifferMain
     @ingroup grpAppSniffer
 \else
     @page pgContribCapture 802.15.4 Packet Capturing with Wireshark
 \endif


 @par Overview

 This package describes, how the traffic on a
 IEEE 802.15.4 wireless sensor network can monitored.

 There are three components involved:
  - a transceiver board connected to a PC and running the sniffer firmware.
  - The Python script  @file ieee802154.py that provides the bridging
    between the transceiver board and wireshark.
  - Wireshark as graphical frontend for displaying the captured frames.

 \if SNIFFERPACKAGE

 Here is a overview of the package contents of
 @tt uracoli-sniffer-<version>.zip:
 <pre>
    uracoli-sniffer-<version>/
    |-- LICENSE
    |-- README.html
    |-- doc
    |   |-- index.html ............ documentation
    |   `-- ...
    |-- firmware .................. sniffer firmware binaries
    |   |-- sniffer_any2400st.hex
    |   |-- sniffer_psk212.hex
    |   `-- ...
    `-- script
        |-- ieee802154.py ......... Python interface script
        `-- ...
 </pre>

 \endif

 The next sections explain the setup and usage of the packet capturing
 under Linux and Windows OS.

  - @subpage pgSnfSW
  - @subpage pgSnfFlash
  - @subpage pgSnfRun
  - @subpage pgLicenses
*/

/**
\if SNIFFERPACKAGE
  @page pgSnfSW Install the Required Software
\else
  @defgroup pgSnfSW Install the Required Software
  @ingroup grpAppSniffer
\endif
 The following software packages have to be installed
 on the PC to run the sniffer application.

 @section swpy Python / pyserial

 The <a href="http://www.python.org">Python</a> interpreter with a version
 below 3.0, e.g. Version 2.6 or 2.7 is needed to run the
 serial-to-wireshark interface script ieee802154.py.
 The <a href="http://pyserial.sourceforge.net/">pyserial</a> module
 provides all functions to access serial interfaces from the python
 interpreter.

  @b @em Linux:

 Install the python package with the preferred package manager of your
 distribution.

  - Debian: <tt>dpkg -i python python-serial</tt>
  - Ubuntu: <tt>sudo apt-get install python python-serial</tt>
  - Suse and Centos/Redhat: install the RPMs.

  @b @em Windows:

  - Download and install \b Python from http://www.python.org/download/.
  - Download and install the package \b win32com (needed for pyserial) from
    http://starship.python.net/~skippy/win32/Downloads.html
  - Download and install the package \b pyserial from
    http://pypi.python.org/pypi/pyserial.

 @section swws Wireshark

 <a href="http://www.wireshark.org/">Wireshark</a> is powerfull tool
 for network data analysis. It is used to display the frames of your
 IEEE-802.15.4 network. Beside the main application, the package comes
 with some handy to use tools like TShark or dumpcap. Since you are new
 to wireshark you should not miss a look into the
 <a href="http://www.wireshark.org/docs/wsug_html_chunked/">Wireshark User Manual</a>.

  @b @em Linux:

  Install the wireshark package with the preferred package manager of your
   distribution.

  - Debian: <tt>dpkg -i wireshark</tt>
  - Ubuntu: <tt>sudo apt-get install wireshark</tt>
  - Suse and Centos/Redhat: install the RPMs.

  @b @em Windows:

  - Download the Windows Installer from
    http://www.wireshark.org/download.html

 @section swsnf @uracoli Sniffer Package.

  The \uracoli sniffer package <tt>uracoli-sniffer-&lt;version&gt;.zip</tt>
  can be obtained from http://uracoli.nongnu.org/download.html. Unzip
  the file in a local tool directory.

 @section swsnf AVR Programming Software.

 In order to flash the firmware on your sniffer board, you need a software.
 The preferred programming tool on Linux is avrdude, while on Windows most
 often AvrStudio is used. Alternatively you can use avrdude on Windows too,
 it comes with the packake WinAVR.

  @b @em Linux:

  Install the package avrdude with the preferred package manager of your
   distribution.

  - Debian: <tt>dpkg -i avrdude</tt>
  - Ubuntu: <tt>sudo apt-get install avrdude</tt>
  - Suse and Centos/Redhat: install the RPMs.

  @b @em Windows:

  - Download AvrStudio from
    http://www.atmel.com/dyn/products/tools_card.asp?tool_id=2725

  - Download the WinAVR package from
    http://winavr.sourceforge.net/download.html

*/

/**

\if SNIFFERPACKAGE
  @page pgSnfFlash Hardware Setup
\else
  @defgroup pgSnfFlash Hardware Setup
  @ingroup grpAppSniffer
\endif

 @section hwfw Flashing the Firmware

 For flashing the firmware on your sniffer board you need a JTAG or ISP
 programmer, e.g. AVR Dragon, AVR ISP or AVR JTAG-ICE MkII.

 The procedure of how to program the firmware and the fuse settings
 into the &micro;Controller is explained in the documentantion of
 your programming software.

 Here is an example for flashing a RCB230 on a Sensor Terminal board
 avrdude via JTAG-ICE or similiar.
 <pre>
 avrdude -P usb -c jtag2 -p atmega1281 \
	 -U lfuse:w:0xe2:m -U hfuse:w:0x11:m -U efuse:w:0xff:m \
	 -U sniffer_stb230b.hex
 </pre>

 On the @subpage pgSnfFwSel page you find a list of supported plattforms
 together with the names of the HEX files,
 the required fuse values and  the baud rate settings.


 @section secSnfConnect Connecting the Board to the PC.

 After connecting the board with the PC, it has to be verified,
 that the board is recognized as a virtual COM port device.

 @b @em Linux:

 The command @tt dmesg helps you to find the assigned serial port.

 The device names are usually /dev/ttyUSB[0-9] for FTDI and CP210x
 based boards and /dev/ttyACM[0-9] for the Raven RZUSB Stick.

 <pre>
  >dmesg | grep tty
  usb 4-1: FTDI USB Serial Device converter now attached to ttyUSB0
  cdc_acm 2-3.1:1.0: ttyACM0: USB ACM device
  usb 2-3.3: cp2101 converter now attached to ttyUSB1
 </pre>


 @b @em Windows:

 The name of the assigned COM port can be found in the "Device Manager".

 A quick way to open the Device Manager (see http://en.wikipedia.org/wiki/Device_Manager)
 is either to type "devmgmt.msc" into the Command Prompt (@tt cmd.exe)
 or do:
 <pre>
 Start -> Run -> devmgmt.msc -> OK
 </pre>


 @note
 If your board is not recognized on your OS, the USB driver may be
 out of date. That is probably the case, if you run Windows
 or Linux prior the kernel version 2.6.29.
 In the package <tt>uracoli-usb-&lt;version&gt;.zip</tt>
 you will find the necessarry drivers, driver patches and a description,
 how to fix this issue. The USB package can be obtained
 from http://uracoli.nongnu.org/download.html.

*/


/**

\if SNIFFERPACKAGE
  @page pgSnfFwSel Firmware Selection
\else
  @defgroup pgSnfFwSel Firmware Selection
  @ingroup grpAppSniffer
\endif

 According to the board you want to use for packet sniffing,
 the aproriate HEX file and fuses have to be selected.

 Here is a list with the settings for the supported plattforms.

 @par Atmel STK541 with RCB

  - \b sniffer_psk230b.hex - RCB w/ AT86RF230 Rev. B
  - \b sniffer_psk230.hex  - RCB w/ AT86RF230 Rev. A
  - \b sniffer_psk231.hex  - RCB w/ AT86RF231
  - \b sniffer_psk212.hex  - RCB w/ AT86RF212
  - \b Fuses: -U lfuse:w:0xe2:m -U hfuse:w:0x11:m -U efuse:w:0xff:m\
       (F_CPU=8MHz w/ internal RC-Oscilator)
  - \b CPU: -p atmega1281
  - \b Baudrate: n/a since this boards use a FT245 with parallel interface.

  @image html stk541_rcb231ad.jpg

 <hr/>

 @par dresden elektronik Senor Terminal Board with RCB

  - \b sniffer_stb230b.hex - RCB w/ AT86RF230 Rev. B
  - \b sniffer_stb230.hex  - RCB w/ AT86RF230 Rev. A
  - \b sniffer_stb231.hex  - RCB w/ AT86RF231
  - \b sniffer_stb212.hex  - RCB w/ AT86RF212
  - \b Fuses: -U lfuse:w:0xe2:m -U hfuse:w:0x11:m -U efuse:w:0xff:m
  - \b CPU: -p atmega1281
  - \b Baudrate: n/a since this boards use a FT245 with parallel interface.

 @image html stb_rcb231ad.jpg

 <hr/>

 @par Atmel RZUSB Stick

  - \b sniffer_rzusb.hex
  - \b Fuses: -U lfuse:w:0xde:m -U hfuse:w:0x91:m -U efuse:w:0xfb:m
  - \b CPU: -p at90usb1287
  - \b Baudrate: n/a since the Stick uses the AT90USB1287 USB PHY.

 @image html rzusbstick.jpg

 <hr/>

 @par AN Solutions USB Dongle

  - \b sniffer_any2400st.hex - ANY2400
  - \b sniffer_any900st.hex  - ANY900
  - \b Fuses: -U lfuse:w:0xe2:m -U hfuse:w:0x11:m -U efuse:w:0xff:m
  - \b CPU: -p atmega1281
  - \b Baudrate: 38400 bit/s

 @image html any_dongle.jpg

  Since the CP210x is connected via UART, the RX oscilator
  needs to be calibrated in order to provide propper signals.
  However with the internal RC oscilator a maximum data rate
  of 38400 bit/s is possible, so this sniffer may drop packets
  in the case when higher network traffic througput occurs.

*/


/**

\if SNIFFERPACKAGE
  @page pgSnfRun Running the Sniffer
\else
  @defgroup pgSnfRun Running the Sniffer
  @ingroup grpAppSniffer
\endof

@par Run the script ieee802154.py

  Start the uracoli-wireshark bridge by typing python
  sniffer/ieee802154.py in a terminal window.

  @code
>python ieee802154.py
Enter Capture Port:/dev/ttyUSB0
uracoli sniffer to wireshark bridge V0.1
 OPTS:
 INPUT:  /dev/ttyUSB0, stb230 V0.1, channel=11, rate=OQPSK250
 OUTPUT: ieee802154
cmd:
  @endcode

The string behind "OUTPUT:" is the name of the capture interface.

  @par Run Wireshark

 @b @em Windows enter the interface name <tt>\\\\.\\pipe\\ieee802154</tt> as life capture interface.

  <pre>
  Capture -> Start
  </pre>

@par Start wireshark

   If wireshark is running, select in the menu Capture/Options or just
   type Ctrl-K, enter \\.\pipe\ieee802154 in the Interface field and
   confirm the dialog with START

   Alternatively you can create a batch file/shell script, which starts
   wireshark directly with the option -i ieee802154.

   images/wscfg.png

   Now capture can be started by clicking this icon:

   images/wsstart.png images/wsrun.png

@par Closing and Reopening a Session

   If you want to save a packet capture logfile, you have to close the
   current session by selecting "Capture?Stop" or "Ctrl-E". After
   "Capture?Start", the wireshark window stays gray shaded. Switch to the
   ieee802154.{exe,py} window and type reopen. This will place the data of
   a pcap file header in the named pipe and will allow wireshark to
   proceed with the frame capturing.

@par Changing Channels and Modulation in a Capture Session

   In the ieee802154.{exe,py} you can change channel (chan) and
   rate/modulation (rate) of the transceiver at any time without
   restarting the wireshark session. NOTE: In the wireshark logfile there
   is no information about the channel or rate/modulation setting stored.


@par Configuration

  You get prompted for the name of the serial port.
  If you type @tt help at the prompt, you get a list
  of available commands.
<pre>
  Commands:
   reopen   - reopens the named pipe and places a pcap header,
              so that wireshark can reconnect.
   chan <n> - set IEEE 802.15.4 channel.
   rate <r> - set IEEE 802.15.4 data rate (e.g. BPSK20, OQPSK100, ...)
   devrst   - reinitialize the sniffer device
   debug    - start python debugger
   info     - show status of sniffer DEVIN
   verbose  - verbose command
   quit     - end session and terminate all threads
   help     - show command help
</pre>

 */


/**

\if SNIFFERPACKAGE
 @page pgLicenses Licenses

   Python is available under the Python Software Foundation License
   (PSF). http://docs.python.org/license.html

   pyserial is available under the Python License.
   http://pyserial.sourceforge.net/appendix.html#license

   win32com A license page could not be found on the Web.

   Wireshark� is available under the GNU General Public License version 2.
   http://www.wireshark.org/about.html

   @uracoli (firmware and converter application) is licensed with a
   Modified BSD License. http://uracoli.nongnu.org/license.html

   Driver for FT245BM is (c) 2000-2008 FTDI Ltd.
   Version 0.2.rc1
   Last updated 2009-02-28 22:28:25 CEST
   http://www.ftdichip.com/
\endif
*/


/*

 @page pgCCULinux Software for Linux


 <pre>
 apt-get install avrdude python py-serial wireshark
 </pre>



<pre>


   The captured frames will displayed with wireshark, which is available
   from [4]http://www.wireshark.org/
../u5isniffer-lin-{version}
|-- index.html .............................. this file
|-- images
|   `-- *.png ............................... documentation graphics
|
|-- driver .................................. Patch instructions for Linux driv
ers
|   |-- ftdi245linux.html
|   |-- ftdi_sio_2.6.13-15-default.patch
|   `-- ftdi_sio_2.6.25.5-1.1-pae.patch
|
|-- firmware
|   |-- sniffer_psk*.hex .................... Atmel ATAVRRZ541
|   `-- sniffer_stb*.hex .................... DE Sensor Terminal Board
|
`-- sniffer
    |-- ieee802154.py  ...................... uracoli-wireshark bridge script
    `-- ...

1.2. Install the USB driver

   The sniffer plattforms normally come with a branded FT245BM, which have
   vendor/product IDs, that differs from the default one.
     * FTDI: VID 0x0403, PID 0x6001, 0x6010,
     * Atmel: VID 0x03EB, PID 0x2109
     * Dresden Elektronik: VID 0x1CF1, PID 0x0001

   Since some professional software presumes the branded VID/PID values,
   it is not always managable to reconfigure or unsolder the eeprom, which
   is connected to the FT245BM. Instead the use of a customized driver
   will be a better choice.

   A detailed description how to get the driver working with modified
   VID/PID can be found [5]in this document.

   With an ISP or JtagICE programmer this applications can be flashed in
   the AVR. The software is compiled using the 8MHz internal clock
   oscilator of the AVR, so the fuses have to be set to:
     * LF: 0xe2 - 8MHz internal RC Osc.
     * HF: 0x11 - without boot loader
     * HF: 0x10 - with boot loader (in this case set LOCK: 0xef -→
       protection of boot section)
     * EF: 0xff

1.4. Install Wireshark

   For your OS you will find the latest version of wireshark here
   [6]http://www.wireshark.org/download.html.

2. Starting a Live Capture Session

2.1. Start the uracoli-wireshark bridge script

   Start the uracoli-wireshark bridge by typing python
   sniffer/ieee802154.py in a terminal window.

   images/snifferlx.png

   Which serial port is assigned to the [7]STB or [8]STK541 board you can
   find out with the dmesg command:
usb 2-3.1: new full speed USB device using ehci_hcd and address 7
usb 2-3.1: configuration #1 chosen from 1 choice
ftdi_sio 2-3.1:1.0: FTDI USB Serial Device converter detected
drivers/usb/serial/ftdi_sio.c: Detected FT232RL
usb 2-3.1: FTDI USB Serial Device converter now attached to ttyUSB0
usb 2-3.1: New USB device found, idVendor=1cf1, idProduct=0001
usb 2-3.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-3.1: Product: SensorTerminalBoard
usb 2-3.1: Manufacturer: dresden elektronik
usb 2-3.1: SerialNumber: DEQA8EHL

   Command line options

   The program ieee802154.{py,exe} can be started with the following
   options.
   -p PORT     Name of the serial port where the sniffer plattform
               is connected, e.g. /dev/ttyUSB0 or COM1.
   -r CAPFILE  Name of a capture file which is read @c mytrace.dat.
   -i PIPE     Name of the named pipe.
                On a Linux system, PIPE can be a absolut path name, e.g.
                /tmp/ieee802154. On a Windows system PIPE is a name in a
                special pipe directory, e.g. foo maps to \\.\pipe\foo.
                [ieee802154]
   -c CHAN     IEEE802.15.4 channel number
   -R RATE     IEEE802.15.4 data rate
   -v          increase verbose level
   -h          show help and exit.
   -V          print version and exit.

  Note:
   * -r and -p can be used only exclusively,
   * -c works only with -p.

   Interactive Commands
   reopen   - reopens the named pipe and places a pcap header,
              so that wireshark can reconnect.
   chan <n> - set new channel to sniff.
   rate <r> - set IEEE 802.15.4 data rate (e.g. BPSK20, OQPSK100, ...)
   devrst   - reinitialize the sniffer device
   debug    - start python debugger
   info     - show status of sniffer DEVIN
   quit     - end session and terminate all threads
   help     - show command help

2.2. Start wireshark

   If wireshark is running, select in the menu Capture/Options or just
   type Ctrl-K, enter the/path/to/ieee802154 in the Interface field and
   confirm the dialog with START

   Alternatively you can create a batch file/shell script, which starts
   wireshark directly with the option -i ieee802154.

   images/wsrun.png

2.3. Closing and Reopening a Session

   If you want to save a packet capture logfile, you have to close the
   current session by selecting "Capture→Stop" or "Ctrl-E". After
   "Capture→Start", the wireshark window stays gray shaded. Switch to the
   ieee802154.{exe,py} window and type reopen. This will place the data of
   a pcap file header in the named pipe and will allow wireshark to
   proceed with the frame capturing.

2.4. Changing Channels and Modulation in a Capture Session

   In the ieee802154.{exe,py} you can change channel (chan) and
   rate/modulation (rate) of the transceiver at any time without
   restarting the wireshark session. NOTE: In the wireshark logfile there
   is no information about the channel or rate/modulation setting stored.

3. Further Reading

3.1. Trouble Shooting

   Error ieee802154.exe: serial.serialutil.SerialException: could not open
   port

   This problem occurs on Windows systems, if the serial port is opened by
   another programm. To resolve this, close the other application, which
   has the port opened.
   Error ieee802154.exe: AttributeError: PortIn instance has no attribute
   tscale

   This problem occurs in the following cases:
     * the RCB does not respond on the serial interface, → check wiring,
       connect a terminal and press the reset button in order to see, if
       the platform is working.
     * the RCB is not programmed with the current sniffer firmware →
       programm the correct firmware hex file.in the RCB.

   There are no frames of my nodes captured in wireshark

   Check in the ieee802154.{py,exe} window, if the channel and rate
   (modulation) is set correctly, use the commands info, channel, rate.

3.2. Links

     * [9]http://www.wireshark.org
     * [10]http://uracoli.nongnu.org
          + [11]Simple Sniffer and Scanner Application (firmware)
          + [12]802.15.4 Packet Capturing with Wireshark (ieee802154.py)
          + [13]FT245BM Driver
     * [14]http://www.dresden-elektronik.de
     * [15]http://www.atmel.com/products/zigbee/default.asp

3.3. Licenses

   Wireshark® is available under the GNU General Public License version 2.
   [16]http://www.wireshark.org/about.html

   µracoli (firmware and converter application) is licensed with a
   Modified BSD License. [17]http://uracoli.nongnu.org/license.html

   Driver for FT245BM is (c) 2000-2008 FTDI Ltd.
   [18]http://www.ftdichip.com/

   Version 0.2.rc1
   Last updated 2009-02-28 22:28:21 CEST

Verweise

   1. http://www.dresden-elektronik.de/shop/prod75.html?language=en
   2. http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4187
   3. http://www.dresden-elektronik.de/shop/cat4_20.html?language=en
   4. http://www.wireshark.org/
   5. file://localhost/mnt/net/axel/1/scratch/sw/Embedded/Savannah/uracoli-appnotes/sniffer/doc/driver/ftdi245linux.html
   6. http://www.wireshark.org/download.html
   7. http://www.dresden-elektronik.de/shop/prod75.html?language=en
   8. http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4187
   9. http://www.wireshark.org/
  10. http://uracoli.nongnu.org/
  11. http://uracoli.nongnu.org/manual/app/group__grpAppSniffer.html
  12. http://uracoli.nongnu.org/manual/contrib/pgContribCapture.html
  13. http://uracoli.nongnu.org/manual/dev/pgDevFTDI245.html
  14. http://www.dresden-elektronik.de/
  15. http://www.atmel.com/products/zigbee/default.asp
  16. http://www.wireshark.org/about.html
  17. http://uracoli.nongnu.org/license.html
  18. http://www.ftdichip.com/



</pre>

 -# 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 pgBoards.
 -# 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


@section sprw Prequisites

@subsection sprw1 Required Software

   Contents of this Package
     * a customized version of the FT245BM CDM driver, which honors the
       special vendor and product IDs of [4]STK541 and [5]STB.
     * the AVR-wireshark interface programm ieee802154.{py,exe}
     * the sniffer firmware for different plattforms
       sniffer_{platform,radio}.hex

   Additional Packages needed

   The captured frames will displayed with wireshark, which is available
   from [6]http://www.wireshark.org/


<pre>
u5isniffer-win-0.0.1
|   index.html .............................. this file
+---images
|       *.png ............................... documentation graphics
|
+---CDM 2.04.06 ............................. FTDI driver with modified inf fil
es
|       ftdibus.inf
|       ftdiport.inf
|       ...
|
+---firmware
|       sniffer_psk*.hex .................... Atmel ATAVRRZ541
|       sniffer_stb*.hex .................... DE Sensor Terminal Board
|
+---sniffer
    +---bin
    |      ieee802154.exe .................. uracoli-wireshark bridge script
    |      ...                               (after py2exe conversion)
    +---src
            ieee802154.py ................... pythons source code
            ...                               (requires packages pyserial and pywin32)

</pre>

<pre style="color:grey">


1.2. Install the USB driver

   The sniffer plattforms normally come with a branded FT245BM, which have
   vendor/product IDs, that differs from the default one.
     * FTDI: VID 0x0403, PID 0x6001, 0x6010,
     * Atmel: VID 0x03EB, PID 0x2109
     * Dresden Elektronik: VID 0x1CF1, PID 0x0001

   Since some professional software presumes the branded VID/PID values,
   it is not always managable to reconfigure or unsolder the eeprom, which
   is connected to the FT245BM. Instead the use of a customized driver
   will be a better choice.

   When the sensor terminal board is connected for the first time, the
   hardware assistent is started. As driver installation directory use the
   directory "CDM 2.04.06" in this package. Since the *.inf files for this
   driver are updated with other VID/PID combinations, the WHQL
   certificate is invalid and you have to confirm the installation of a
   driver with a broken signature.

1.3. Flashing the firmware

   In the directory firmware the hex files for different sniffer
   plattforms are stored.
     * sniffer_psk230.hex → STK w/ AT86RF230 Rev.A RCB
     * sniffer_psk230b.hex → STK w/ AT86RF230 Rev.B RCB
     * sniffer_psk231.hex → STK w/ AT86RF231 RCB
     * sniffer_psk212.hex → STK w/ AT86RF212 RCB
     * sniffer_stb230.hex → STB w/ AT86RF230 Rev.A RCB
     * sniffer_stb230b.hex → STB w/ AT86RF230 Rev.B RCB
     * sniffer_stb231.hex → STB w/ AT86RF231 RCB
     * sniffer_stb212.hex → STB w/ AT86RF212 RCB

   With an ISP or JtagICE programmer this applications can be flashed in
   the AVR. The software is compiled using the 8MHz internal clock
   oscilator of the AVR, so the fuses have to be set to:
     * LF: 0xe2 - 8MHz internal RC Osc.
     * HF: 0x11 - without boot loader
     * HF: 0x10 - with boot loader (in this case set LOCK: 0xef -→
       protection of boot section)
     * EF: 0xff

1.4. Install Wireshark

   For your OS you will find the latest version of wireshark here
   [7]http://www.wireshark.org/download.html.

2. Starting a Live Capture Session

2.1. Start the uracoli-wireshark bridge script

   The uracoli-wireshark bridge script will be started by clicking on the
   program icon ieee802154.exe in the folder sniffer. Since there are no
   command line options passed to the programm, you get prompted to enter
   the serial port, where the sniffer plattform is connected. You can get
   this information from the hardware manager. The program 802154.{py,exe}
   runs in a text window, where you can type commands. Type help to view a
   list of the available commands.

   images/sniffer.png Sensor Terminal Board in Hardware Manager
   Command line options

   The program ieee802154.{py,exe} can be started with the following
   options.
   -p PORT     Name of the serial port where the sniffer plattform
               is connected, e.g. /dev/ttyUSB0 or COM1.
   -r CAPFILE  Name of a capture file which is read @c mytrace.dat.
   -i PIPE     Name of the named pipe.
                On a Linux system, PIPE can be a absolut path name, e.g.
                /tmp/ieee802154. On a Windows system PIPE is a name in a
                special pipe directory, e.g. foo maps to \\.\pipe\foo.
                [ieee802154]
   -c CHAN     IEEE802.15.4 channel number
   -R RATE     IEEE802.15.4 data rate
   -v          increase verbose level
   -h          show help and exit.
   -V          print version and exit.

  Note:
   * -r and -p can be used only exclusively,
   * -c works only with -p.

   Interactive Commands
   reopen   - reopens the named pipe and places a pcap header,
              so that wireshark can reconnect.
   chan <n> - set new channel to sniff.
   rate <r> - set IEEE 802.15.4 data rate (e.g. BPSK20, OQPSK100, ...)
   devrst   - reinitialize the sniffer device
   debug    - start python debugger
   info     - show status of sniffer DEVIN
   quit     - end session and terminate all threads
   help     - show command help

2.2. Start wireshark

   If wireshark is running, select in the menu Capture/Options or just
   type Ctrl-K, enter \\.\pipe\ieee802154 in the Interface field and
   confirm the dialog with START

   Alternatively you can create a batch file/shell script, which starts
   wireshark directly with the option -i ieee802154.

   images/wscfg.png

   Now capture can be started by clicking this icon:

   images/wsstart.png images/wsrun.png

2.3. Closing and Reopening a Session

   If you want to save a packet capture logfile, you have to close the
   current session by selecting "Capture→Stop" or "Ctrl-E". After
   "Capture→Start", the wireshark window stays gray shaded. Switch to the
   ieee802154.{exe,py} window and type reopen. This will place the data of
   a pcap file header in the named pipe and will allow wireshark to
   proceed with the frame capturing.

2.4. Changing Channels and Modulation in a Capture Session

   In the ieee802154.{exe,py} you can change channel (chan) and
   rate/modulation (rate) of the transceiver at any time without
   restarting the wireshark session. NOTE: In the wireshark logfile there
   is no information about the channel or rate/modulation setting stored.

3. Further Reading

3.1. Trouble Shooting

   Error ieee802154.exe: serial.serialutil.SerialException: could not open
   port

   This problem occurs on Windows systems, if the serial port is opened by
   another programm. To resolve this, close the other application, which
   has the port opened.
   Error ieee802154.exe: AttributeError: PortIn instance has no attribute
   tscale

   This problem occurs in the following cases:
     * the RCB does not respond on the serial interface, → check wiring,
       connect a terminal and press the reset button in order to see, if
       the platform is working.
     * the RCB is not programmed with the current sniffer firmware →
       programm the correct firmware hex file.in the RCB.

   There are no frames of my nodes captured in wireshark

   Check in the ieee802154.{py,exe} window, if the channel and rate
   (modulation) is set correctly, use the commands info, channel, rate.

3.2. Links

     * [8]http://www.wireshark.org
     * [9]http://uracoli.nongnu.org
          + [10]Simple Sniffer and Scanner Application (firmware)
          + [11]802.15.4 Packet Capturing with Wireshark (ieee802154.py)
          + [12]FT245BM Driver
     * [13]http://www.dresden-elektronik.de
     * [14]http://www.atmel.com/products/zigbee/default.asp

3.3. Licenses

   Wireshark® is available under the GNU General Public License version 2.
   [15]http://www.wireshark.org/about.html

   µracoli (firmware and converter application) is licensed with a
   Modified BSD License. [16]http://uracoli.nongnu.org/license.html

   Driver for FT245BM is (c) 2000-2008 FTDI Ltd.
   [17]http://www.ftdichip.com/

   Version 0.2.rc1
   Last updated 2009-02-28 22:28:25 CEST

Verweise

   1. http://www.dresden-elektronik.de/shop/prod75.html?language=en
   2. http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4187
   3. http://www.dresden-elektronik.de/shop/cat4_20.html?language=en
   4. http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4187
   5. http://www.dresden-elektronik.de/shop/prod75.html?language=en
   6. http://www.wireshark.org/
   7. http://www.wireshark.org/download.html
   8. http://www.wireshark.org/
   9. http://uracoli.nongnu.org/
  10. http://uracoli.nongnu.org/manual/app/group__grpAppSniffer.html
  11. http://uracoli.nongnu.org/manual/contrib/pgContribCapture.html
  12. http://uracoli.nongnu.org/manual/dev/pgDevFTDI245.html
  13. http://www.dresden-elektronik.de/
  14. http://www.atmel.com/products/zigbee/default.asp
  15. http://www.wireshark.org/about.html
  16. http://uracoli.nongnu.org/license.html
  17. http://www.ftdichip.com/

</pre>


 (@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 pgBoards.
 -# 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.


 This has to be in the uracoli-usb package

 The Sniffer Plattforms can be recognized
 with the following Vendor/Device IDs.

 - AN-Solutions Dongle: 10c4:ea60 (CP210x Composite Device)
 - Atmel STK541: 03EB:2109 (FT245BM w/ EEPROM)
 - DE Sensor Terminal Board: 1CF1:0001 (FT245BM w/ EEPROM)
 - STK541 and STB w/o EEPROM: 0403:6001, 0403:0x6010 (unbranded FTDI FT245BM)
 - RZUSB Stick w/ uracoli Firmware: 16c0:0887

 See also http://uracoli.nongnu.org/manual/dev/pgDevUSB.html for
 details about the Linux / Windows driver configuration.

 Since kernel 2.6.29 all of the above boards are automatically
 recognized. For older kernels the driver ftdi_sio.[ch] needs a patch,
 see http://uracoli.nongnu.org/manual/dev/pgDevFTDI245Linux.html


 After connecting the board with the PC, the vendor and deivec ID should be
 found with the command <tt>lsusb</tt>

 <pre>
  linux.box> ../uracoli >lsusb
    Bus 006 Device 001: ID 1d6b:0001 ...
    Bus 005 Device 002: ID 05e3:0502 ...
    Bus 005 Device 001: ID 1d6b:0001 ...
    Bus 004 Device 002: ID 03eb:2109 Atmel Corp. <=== STK541
    Bus 004 Device 001: ID 1d6b:0001 ...
    Bus 003 Device 001: ID 1d6b:0001 ...
    Bus 002 Device 004: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x Composite Device
    Bus 002 Device 003: ID 16c0:0887 VOTI <=== uracoli Sniffer
    Bus 002 Device 002: ID 0409:005a ...
 </pre>


 */
