µracoli Manual  Version foo
802.15.4 Packet Sniffer

Overview

The traffic in a IEEE 802.15.4 network can be monitored with a common transceiver board and the µracoli sniffer firmware. The setup of a sniffer requires the following components:

  • A transceiver board running the sniffer firmware. It is connected to the PC via UART or USB.
  • The Python script 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.
  • Wireshark/tshark as frontend for display and analysis the captured frames.

Prerequisites

Additional Software
  • Python 2.x with pyserial
  • Wireshark
  • Firmware Programming Tool

Python with pyserial is used as interface between the host interface (UART or USB) and the Wireshark or tcpdump tool.

Wireshark is a comprehensive and sophisticated network analysis tool.

In order to flash the sniffer firmware to the target board, a flash programming tool (JTAG-ICE, AVR-Dragon, Serial Bootloader, ...) and a programming software is required.

Firmware Installation

Compiling

Check out if your hardware supports sniffer functionality

$ make -C uracoli-<version>/src/sniffer list
make: Entering directory `/home/uracolix/uracoli-<version>/src/sniffer'
any2400 : A.N. Solutions ANY Brick
any2400st : A.N. Solutions ANY Stick
any900 : A.N. Solutions ANY Brick
any900st : A.N. Solutions ANY Stick
atrcb256rfr2xpro : Atmel ATmega256RFR2 ZigBit Xplained Pro Extension
...
zgbh230 : ATZGB.com evaluation board
zgbh231 : ATZGB.com evaluation board
make: Leaving directory `/home/uracolix/uracoli-<version>/src/sniffer'

The firmware is compiled with the command:

$ make -C uracoli-<version>/src/sniffer <myboard>

and can be found in uracoli- <version>/src/bin/sniffer_<myboardh>.hex/elf

Programming

The programming of the firmware and the fuse settings of the µ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.

 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
 

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 µracoli source code package (see http://uracoli.nongnu.org/buildprocess.html).

Running the Sniffer

Command Line Usage

The sniffer application is launched with the following command in Linux

$ python script/sniffer.py -p /dev/ttyUSB0 | wireshark -ki -

or with this command in Windows:

$ python script/sniffer.py -p COM1 | wireshark -ki -

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

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

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:

$ python script/sniffer.py -p /dev/ttyUSB0 -c 26 > log.pcap

An option of storing the data in the background is using the Linux/Unix command tee:

$ python script/sniffer.py -p /dev/ttyUSB0 -c 26 | tee log.pcap | wireshark -ki -

If just a terminal without an X-Windows is available, the tool tshark can be used as backend:

$ python script/sniffer.py -p /dev/ttyUSB0 -c 26 | tshark -i -

The Lua dissector for the P2P protocoll, that is used, e.g. for the wireless UART, can be enabled with the following command line:

$ python script/sniffer.py -p /dev/ttyUSB0 -c 26 | wireshark -Xlua_script:script/p2p.lua -ki -
GUI Usage

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

uracoli_sniffer.png
Wireshark and sniffer.py

Terminal Interface

This section describes the UART interface of the sniffer firmware. The interfacing with wireshark is described in section 802.15.4 Packet Sniffer.

The application provides two modes:

  • The Scan Mode scans over the selected channels and displays statistics of the received frames. The channel is switched after the time SCAN_PERIOD_MS.
  • The Sniff Mode receives on one selected channel and dumps the frames on the host interface. This mode can used for live capturing WPAN data with wireshark (see contibution guide for more details).
Usage

The following commands are available in the terminal:

Mode Commands:

  • idle, Keys: I, <SPACE>
    Set application to idle mode and transceiver to state TRX_OFF.
  • scan
    Scan for frames on the enabled channels (see also commands cmask, cmset and cmclr)
  • sniff
    Start sniffing frames on the current channel and dump the received packets of the hostinterface (see command parms).

Parameter Commands:

  • parms
    Display current parameter settings.
  • chan <CHAN>, Keys: + , -
    Set current channel (for sniffing). "+" increments the current channel by one, "-" decrements by one.
  • cmclr <chan>
    Erase the channel bit in cmask.
  • cmset <chan>
    Set the channel bit in cmask.
  • cmask <mask>
    Set the 32 bit channel mask. mask can be a hexadecimal value, e.g. 0x07fff800
  • cpage <page>
    Set current channel page ({not yet supported})
  • drate <ratestr>
    Set current data rate of transceiver. ratestr = {BPSK{20,40}, OQPSK{100,200,250,400,500,1000,2000}}
  • chkcrc <[0|1]>
    if 0, discard frames with invalid CRC, if 1, report also frames with invalid CRC.
Scan Mode

The Scan Mode is started with the command scan. The scanned channels can be configured with the channel mask and the commands cmset, cmclr and cmask.

IEEE Channels, Channel Mask and Channel Page in Scan Mode

IEEE 802.15.4 uses a 32 bit channel mask. Since the standard uses just 26 channels (0 for 868 MHz, 1-10 for 915 MHz and 11-26 for 2.4 GHz) the upper 5 bits of the channel mask are currently used by the value channel page. The channel page identifies the modulation method used.

In order to enable channel 15 in the channel mask for scanning, you can use the command cmask 0x00008000 or cmset 15.

> parms
SUPP_CMSK: 0x07fff800 ....... shows the supported channels of the radio
CURR_CMSK: 0x04008800 ....... channel mask used for scanning (11,15,26)
CURR_CHAN: 11 ............... channel used for sniffing
CURR_PAGE: 0  ............... unsupported yet
Display of the Scan Results

In scan mode the application switches from channel to channel and collects the statistics of the received frames. The information can be displayed in a terminal as table (see example below, which scans only channels 11 and 15, cmask = 0x00008800).

scan

Scanning channels, scan period 2000ms bad Avg. 802.15.4 frames chan frm crc ed lqi B D A C PER 11 0 0 0 0 0 0 0 0 0 12 n/a 13 n/a 14 n/a 15 62 0 71 255 0 62 0 0 0 16 n/a 17 n/a 18 n/a 19 n/a 20 n/a 21 n/a 22 n/a 23 n/a 24 n/a 25 n/a 26 1 1 0 0 0 0 0 0 100 === ur 0 err 0 frames: 63 ===

The columns of the table have the following meaning:

             bad    Avg.         802.15.4 frames
chan   frm   crc   ed lqi      B     D     A     C  PER
 |      |     |    |   |       |     |     |     |   +... Estimated packet error rate
 |      |     |    |   |       |     |     |     +....... number of rx'd command frames
 |      |     |    |   |       |     |     +............. number of rx'd ACK frames
 |      |     |    |   |       |     +................... number of rx'd data frames
 |      |     |    |   |       +......................... number of rx'd beacon frames
 |      |     |    |   +................................. average LQI of frames on this channel
 |      |     |    +..................................... average energy value frames on this channel
 |      |     +.......................................... number of frames with bad CRC
 |      +................................................ number of received frames
 +....................................................... channel number
Sniffer Mode

The Sniff Mode is started with the command sniff. The channel which should be monitored is set with the command chan. In the sniff mode, each received frame is transfered over the host interface to the PC application.

Data Transfer in Sniffer Mode

The binary protocoll used for transfer the received frames over the host interface in sniff-mode has the following format:

 +-------+--------+--------+------------+--------+
 | SOF   |  LEN   | TSTAMP | FRAMEDATA  | EOF    |
 +-------+--------+--------+------------+--------+
 | 1Byte | 1 Byte | 8 Byte | 1-127 Byte | 1 Byte |
 +-------+--------+--------+------------+--------+
 
Parameters
SOFStart of frame field (0x01)
LENLength of packet (size of time stamp and frame size) (8 ... 133)
TSTAMPTime structure (4 Byte seconds, 4 byte micro seconds)
FRAMEDATAOctets of the frame (the data does not contain the IEEE 802.15.4 PHR with the reserved bit value).
EOFEnd of frame field.