whsniff: A C repository from homewsn

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"
```
1. Reload udev rules
```
sudo udevadm control --reload
```
1. 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 root@192.168.1.202 "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 root@192.168.1.202 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