homewsn / whsniff

A packet converter for sniffing IEEE 802.15.4 wireless sensor networks

This repository is a part of the HomeWSN project.

Whsniff is a command line utility that interfaces TI CC2531 USB dongle with Wireshark for capturing and displaying IEEE 802.15.4 traffic at 2.4 GHz.

This utility only works on Linux (including OpenWrt). For Windows download and install the SmartRF Packet Sniffer from TI website.

Whsniff reads the packets from TI CC2531 USB dongle with sniffer_fw_cc2531 firmware, converts to the PCAP format and writes to the standard output(stdout).

Building (Linux)

• Install libusb-1.0-0-dev:

$ sudo apt-get install libusb-1.0-0-dev

• Download the latest release in tarball from github and untar it. Then build and install whsniff.

$ curl -L https://github.com/homewsn/whsniff/archive/v1.3.tar.gz | tar zx
$ cd whsniff-1.3
$ make
$ sudo make install

Building (macOS)

• Install libusb via Homebrew (or your preferred package manager):

$ brew install libusb

• Download the latest release in tarball from github and untar it. Then build and install whsniff.

$ curl -L https://github.com/homewsn/whsniff/archive/v1.3.tar.gz | tar zx
$ cd whsniff-1.3
$ make
$ sudo make install

Building (OpenWrt)

• Install OpenWrt buildroot.
• Add the following line to the feeds.conf.default in the OpenWrt buildroot:

src-git homewsn https://github.com/homewsn/homewsn.openwrt.packages.git

• This feed should be included and enabled by default in the OpenWrt buildroot. To install all its package definitions, run:

$ ./scripts/feeds update homewsn
$ ./scripts/feeds install -a -p homewsn

• The packages should now appear in menuconfig. You can find whsniff in the Network menu.

How to use (Locally)

• Connect CC2531 USB dongle to your Linux or macOS computer.
• Open a terminal session on the desktop where you have Wireshark installed and enter the following commands:

$ wireshark -k -i <( path/to/whsniff -c channel_number )
or
$ path/to/whsniff -c channel_number | wireshark -k -i -
or
$ mkfifo /tmp/pipes/whsniff
$ path/to/whsniff -c channel_number > /tmp/pipes/whsniff

• You can also save the output to a file to analyze it later using Wireshark:

$ path/to/whsniff -c channel_number > filename.pcap

• You can also let whsniff save the output to a file, whsniff will generate a file name that indicates sniffing start date/time

$ path/to/whsniff -c channel_number -f

• You can also let whsniff save the output to a file, and automatically restart sniffing every hour (-h) or day (-d) so that a single file is not too huge

$ path/to/whsniff -c channel_number -f -h
$ path/to/whsniff -c channel_number -f -d

• You can also keep the original FCS sent by the CC2531 through the -k option. The original FCS contains the RSSI and LQI. It can be interpreted by wireshark as a "TI CC24xx FCS format":

$ path/to/whsniff -k -c channel_number > /tmp/pipes/whsniff

• If you see something like libusb: error [_get_usbfs_fd] libusb couldn't open USB device /dev/bus/usb/001/006: Permission denied you can use udev

  1. Add below contents to /etc/udev/rules.d/54-cc2531.rules

  ATTR{idVendor}=="0451", ATTR{idProduct}=="16ae",MODE="660", GROUP="dialout"

  2. Reload udev rules

  sudo udevadm control --reload

  3. Add yourself to the group dialout, Log out and in again.

  sudo usermod -aG dialout $USER 

How to use (Remotely)

• Connect CC2531 USB dongle to remote Linux PC or OpenWrt device, then start whsniff remotely with ssh from the desktop where you have Wireshark installed.
• For Linux open a terminal session on the desktop and enter the following command:

$ ssh [email protected] "whsniff -c 18" | wireshark -k -i -

where 192.168.1.202 is an IP address of the computer where dongle is connected and 18 is a channel number.

• For Windows install PuTTY with extension plink.exe from PuTTY Download Page, then open a command prompt window and enter the following command:

> "C:\Program Files\PuTTY\plink.exe" -batch -ssh -pw password [email protected] whsniff -c 18 | "C:\Program Files\Wireshark\wireshark.exe" -k -i -

where password is a root password, 192.168.1.202 is an IP address of the computer where dongle is connected and 18 is a channel number.

License

GNU GPL v 2.0