b/* Copyright (c) 2007 - 2012 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 Sniffing
 \else
     @page pgSnfMain 802.15.4 Packet Sniffing
 \endif

 @par Overview

 The traffic in a IEEE 802.15.4 network can be monitored with a common
 transceiver board and the @uracoli sniffer firmware. The setup of a sniffer
 requires the following components:
 - A <b>transceiver board</b> running the sniffer firmware. It is connected to
   the PC via UART or USB.
 - The Python script  @b sniffer.py. It realizes the bridging of the data
   between the transceiver board and wireshark and it enables the user to select
   channels and modulations.
 - <b>Wireshark/tshark</b> as frontend for display and analysis the captured
   frames.

 The next sections explain the setup and usage of the @uracoli-sniffer under
 Linux and Windows.

 \if SNIFFERPACKAGE
  - @ref pgSnfSW
  - @ref pgSnfFwSel
  - @ref pgSnfRun
  - @ref pgLicenses
 \else
  - @subpage pgSnfSW
  - @subpage pgSnfFwSel
  - @subpage pgSnfRun

 @par Furter reading
 How the UART interface of the firmware works, is described in section
 @ref grpAppSniffer.

 \endif
*/

/**
 @page pgSnfSW Software Installation

 The following software packages are required to run the sniffer:
 - @ref swsnfpkg
 - @ref swsnfavr
 - @ref swpy
 - @ref swws

 @section swsnfpkg @uracoli Sniffer Package

 Download the package <tt>uracoli-sniffer-&lt;version&gt;.zip</tt>
 from http://uracoli.nongnu.org/download.html and
 unzip it into a local directory. In the package the following files
 and folders are contained:
 <pre>
    uracoli-sniffer-<version>/
    |-- LICENSE
    |-- README.html
    |-- doc ....................... doxygen html documentation
    |   |-- index.html
    |   `-- ...
    |-- firmware .................. sniffer firmware binaries
    |   |-- sniffer_any2400st.hex
    |   |-- sniffer_psk212.hex
    |   `-- ...
    `-- script
        |-- sniffer.py ............ Python interface script
        |-- p2p.lua ............... example LUA dissector for Wireshark
        `-- ...
 </pre>

 @section swsnfavr AVR Programming Software

 In order to flash the sniffer firmware in the transceiver board, you need
 either a preinstalled bootloader in the MCU or a hardware programmer, e.g. like
 AVR-Dragon, JTAG-ICE, AVR ISP, USB-ASP, .... The preferred programming tool
 under Linux is @b avrdude. On Windows mostly <b>Atmel AVR Studio</b> is used.

 @par Linux:
  Install the package @c avrdude with the 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.

 @par Windows:
  On Windows very often Atmel AVR Studio is used for flashing AVR controllers.
  Alternatively you can also use @c avrdude on Windows, it comes either with
  @em WinAVR or it can be downloaded also as a seperate package.
  - Atmel AVR Studio
    * http://www.atmel.com/microsite/avr_studio_5/
  - WinAVR
    http://winavr.sourceforge.net/download.html
  - @c avrdude for Windows:
    http://tomeko.net/other/avrdude/building_avrdude.php \n
    <em>Below the compile description, there is a link to the
    file</em> @c avrdude.zip.

 @section swpy Python / pyserial

 The <a href="http://www.python.org">Python</a> interpreter with version 2.6. or
 2.7 (but version must be below 3.0) is required to execute the script
 @c sniffer.py.
 Additionaly the module <a href="http://pyserial.sourceforge.net/">pyserial</a>
 is required for access to the serial port.

 @par Linux:
 Install the Python packages with the preferred package manager of your
 distribution, e.g.
  - 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 @c python and @c python-serial.

  @par Windows:
  Download and install the following packages:
  - Python: http://www.python.org/download/
  - The easiest way to install +pyserial+ on Windows is using the tool +pip+ as
    described here:
    <a href="http://uracoli.nongnu.org/gettingstarted.html#_installing_and_upgrading_python">Installing and Upgrading Python</a>

 @section swws Wireshark

 <a href="http://www.wireshark.org/">Wireshark</a> is powerful tool for network
 traffic monitoring. It is used to display, inspect and analyze the
 IEEE-802.15.4 frames captured from the transceiver board.
 Beside the main application @c wireshark, the package comes with some other handy
 command line tools like @c tshark or @c dumpcap. If you are a new wireshark user,
 you should not miss a look into the
 <a href="http://www.wireshark.org/docs/wsug_html_chunked/">Wireshark User Manual</a>.

 @note Since the script @c sniffer.py saves the monitored data in PCAP format
 (see http://en.wikipedia.org/wiki/Pcap), wireshark needs not mandatory to be
 installed on the PC running the sniffer application. The captured PCAP files
 can be analyzed also offline on a seperate PC. However for a data life display,
 a wireshark installation is required.

 @par 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.

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

*/


/**
 @page pgSnfFwSel Firmware Installation


 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>


 According to the transceiver board you want to use as sniffer hardware,
 the aproriate HEX file and right fuse settings have to be programmed.
 Here is a list with the settings for the supported plattforms.

 @note
 If the firmware of your transceiver board is not contained in sniffer package,
 you can compile the firmware from the @uracoli source code package
 (see http://uracoli.nongnu.org/buildprocess.html).

 @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.

*/


/**
 @page pgSnfRun Running the Sniffer


 @section secSnfConn Connecting Board and PC

 Most of the current transceiver boards are equipped with a USB connector. If
 the USB cord is plugged into the PC, the OS will load a driver and assign
 a virtual serial port. Before starting the sniffer, the name of the serial
 port needs to be determined.

 @par Linux:

 The device names are usually:
  - <code>/dev/ttyS[0-9]</code> for regular RS232 serial ports,
  - <code>/dev/ttyUSB[0-9]</code> for FTDI and CP210x based boards and
  - <code>/dev/ttyACM[0-9]</code> for CDC devices like the Raven RZUSB stick.

 The assigned name of a serial port can be found with the command @c dmesg.
 @code
  $ 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
 @endcode


 @par Windows

 The name of the assigned COM port can be found with the <b>Device Manager</b>.
 A quick way to open this tool (see http://en.wikipedia.org/wiki/Device_Manager)
 is either to type @c devmgmt.msc in @c cmd.exe window
 or click: <code>Start -> Run -> devmgmt.msc -> OK</code>


 @section secSnfRun Running the Sniffer

 @par Command Line Usage

 The sniffer application is launched with the following command
 in @b Linux
 @code
 $ python script/sniffer.py -p /dev/ttyUSB0 | wireshark -ki -
 @endcode
 or with this command in @b Windows:
 @code
 $ python script/sniffer.py -p COM1 | wireshark -ki -
 @endcode

 All command line options of script are displayed with the command
 <code>python script/sniffer.py -h</code>. The following options are supported

 @code
    -p PORT:
        Serial port, the data rate is optionally seperated by ":", e.g. -p COM1:38400
    -c CHANNEL:
        Initial channel to be used.
    -r RATE:
        Initial data rate to be used.
    -h:
        Show help and exit.
    -V:
        Show version and exit.
 @endcode

 After running this command from the command line, the sniffer control window
 and the wireshark window will appear on the screen.

 Another method of running the sniffer tool is simply to collect the captured
 data in a logfile:
 @code
 $ python script/sniffer.py -p /dev/ttyUSB0 -c 26 > log.pcap
 @endcode

 An option of storing the data in the background is using the Linux/Unix command
 <code>tee</code>:
 @code
 $ python script/sniffer.py -p /dev/ttyUSB0 -c 26 | tee log.pcap | wireshark -ki -
 @endcode

 If just a terminal without an X-Windows is available, the tool @c tshark can be
 used as backend:
 @code
 $ python script/sniffer.py -p /dev/ttyUSB0 -c 26 | tshark -i -
 @endcode

 The Lua dissector for the P2P protocoll, that is used, e.g. for the wireless
 UART, can be enabled with the following command line:
 @code
 $ python script/sniffer.py -p /dev/ttyUSB0 -c 26 | wireshark -Xlua_script:script/p2p.lua -ki -
 @endcode


 @par GUI Usage

 In the sniffer control window there are two the scroll lists: @b Channel
 (see option @c -c) and  @b Rate  (see option @c -r) this transceiver parameters
 can be canged interactively during a session. With the button @b Quit the GUI
 and the tool @c sniffer.py is closed, but wireshark remains open. A quick method
 to exit @c sniffer.py and @c wireshark is pressing "Ctrl-C" at the command line.

 @image html "uracoli_sniffer.png" "Wireshark and sniffer.py" width="40%"

*/

/**
 \if SNIFFERPACKAGE
 @page pgLicenses Licenses

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

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

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

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

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

 \endif
*/
