Merge pull request https://github.com/RIOT-OS/applications/pull/43 from miri64/sniffer/fix/doc

sniffer: various documentation improvements

sniffer/README.md

@@ -1,7 +1,7 @@
 About
 =====
 
-This application is build to run together with the script `RIOTBASE/dist/tools/sniffer/sniffer.py` as sniffer for (wireless) data traffic. This application works with any board with any network device that supports the gnrc network stack (or precisely the gnrc parts up to the link-layer). Further the network device (and it's driver) needs to support promiscuous and raw mode for usable output. Finally the board needs to include auto-initialization code for the targeted network device.
+This application is build to run together with the script `./tools/sniffer.py` as sniffer for (wireless) data traffic. This application works with any board with any network device that supports the gnrc network stack (or precisely the gnrc parts up to the link-layer). Further the network device (and it's driver) needs to support promiscuous and raw mode for usable output. Finally the board needs to include auto-initialization code for the targeted network device.
 
 
 Usage

sniffer/tools/README.md

@@ -46,36 +46,18 @@ $ RIOTBASE=<path/to/RIOT> BOARD=<name> make clean all flash
 2.  Run the `sniffer.py` script (change to subfolder `tools/`) as follows :
     For serial port:
 ```
-$ ./sniffer.py serial <tty> <baudrate> <channel> [outfile]
+$ ./sniffer.py [-b baudrate] <tty> <channel> [outfile]
 ```
 For network socket:
 ```
-$ ./sniffer.py socket <host> <port> <channel> [outfile]
+$ ./sniffer.py <host>:<port> <channel> [outfile]
 ```
 
-The script has the following parameters:
+For detailed information on the parameters use the scripts on-line help:
-
-- **connType:** The type of connection to use. Either `serial` for serial ports or
-                `socket` for network sockets.
-- **host:** The host if the `socket` connection type is in use.
-- **port:** The port of the host if the `socket` connection type is in use.
-- **tty:** The serial port the RIOT board is connected to. Under Linux, this is
-           typically something like /dev/ttyUSB0 or /dev/ttyACM0. Under Windows,
-           this is typically something like COM0 or COM1. This option is used
-           for the `serial` connection type.
-- **baudrate:** The baudrate the serial port is configured to. The default in
-                RIOT is 115200, though this is defined per board and some boards
-                have some other value defined per default. NOTE: when sniffing
-                networks where the on-air bitrate is > baudrate, it makes sense
-                to increase the baudrate so no data is skipped when sniffing.
-                This option is used for the `serial` connection type.
-- **channel:** The radio channel to use when sniffing. Possible values vary and
-               depend on the link-layer that is sniffed. This parameter is
-               ignored when sniffing wired networks.
-- **[outfile]:** When this parameter is specified, the sniffer output is saved
-               into this file. See the examples below for alternatives to
-               specifying this parameter. (optional)
 
+```
+./sniffer.py -h
+```
 
 ### Examples
 
@@ -88,14 +70,14 @@ is used.
 
 Dump packets to a file:
 ```
-$ ./sniffer.py serial /dev/ttyUSB1 500000 17 > foo.pcap
+$ ./sniffer.py -b 500000 /dev/ttyUSB1 17 foo.pcap
 ```
 
 This .pcap can then be opened in Wireshark.
 
 Alternatively for live captures, you can pipe directly into Wireshark with:
 ```
-$ ./sniffer.py serial /dev/ttyUSB1 500000 17 | wireshark -k -i -
+$ ./sniffer.py -b 500000 /dev/ttyUSB1 17 | wireshark -k -i -
 ```
 
 #### Windows (serial)
@@ -104,7 +86,7 @@ For windows you can use the optional third argument to output to a
 .pcap:
 
 ```
-$ ./sniffer.py serial COM1 500000 17 foo.pcap
+$ ./sniffer.py -b 500000 COM1 17 foo.pcap
 ```
 
 #### IoT-Lab Testbed (socket)
@@ -119,6 +101,6 @@ ssh -L 20000:_node-id_:20000 _user_@_site_.iot-lab.info
 Then you can dump or observe the traffic generated by the other nodes running the `gnrc_networking`
 application via one of the following commands:
 ```
-$ ./sniffer.py socket localhost 20000 26 > foo.pcap
+$ ./sniffer.py localhost:20000 26 foo.pcap
-$ ./sniffer.py socket localhost 20000 26 | wireshark -k -i -
+$ ./sniffer.py localhost:20000 26 | wireshark -k -i -
 ```

sniffer/tools/sniffer.py

@@ -50,6 +50,8 @@ SIG = 0
 SNAPLEN = 0xffff
 NETWORK = 230       # 802.15.4 no FCS
 
+DEFAULT_BAUDRATE = 115200
+
 
 def configure_interface(port, channel):
     line = ""
@@ -141,16 +143,17 @@ def main():
     else:
         default_outfile = sys.stdout
     p = argparse.ArgumentParser()
-    p.add_argument("-b", "--baudrate", type=int, default=115200,
+    p.add_argument("-b", "--baudrate", type=int, default=DEFAULT_BAUDRATE,
                    help="Baudrate of the serial port (only evaluated "
-                        "for non TCP-terminal)")
+                        "for non TCP-terminal, default: %d)" %
+                        DEFAULT_BAUDRATE)
     p.add_argument("conn", metavar="tty/host:port", type=str,
                    help="Serial port or TCP (host, port) tuple to "
                         "terminal with sniffer application")
     p.add_argument("channel", type=int, help="Channel to sniff on")
     p.add_argument("outfile", type=argparse.FileType("w+b"),
                    default=default_outfile, nargs="?",
-                   help="PCAP file to output to")
+                   help="PCAP file to output to (default: stdout)")
     args = p.parse_args()
 
     conn = connect(args)