Ubisys IEEE 802.15.4 usb stic with wireshark... User manual


REFERENCE MANUAL


2www.ubisys.de

1. Overview
Welcome to your ubisys !
This reference manual provides operating and maintenance instructions, command references etc. If
you have any questions or need additional support, software or drivers, please visit our engineering
support pages.
http://www.ubisys.de/engineering/support.html

3www.ubisys.de

2. Contents
1. Overview 2
2. Contents 3
3. Features 4
4. Installation Microsoft Windows 5
5. Installation Linux 7
6. Setting the Channel for Capture Microsoft Windows 10
7. Setting the Channel for Capture Linux 11
8. Using Wireshark for IEEE 802.15.4 Captures (Quick Introduction) 13
9. Using Wireshark to Analyze Encrypted ZigBee PRO Traffic 19
10. Multiple-Channel Capture and Diversity 22
11. Troubleshooting 25
12. Physical Dimensions 26
13. Ordering Information 27
14. Declaration of Conformity 28
15. Revision History 29
16. Contact 30

4www.ubisys.de

3. Features
- Turns your ubisys IEEE 802.15.4 stick into a powerful
used and actively maintained open-source network protocol analyzer software available to date
- Covers all channels in the 2.4 GHz band, i.e. channels 11-26 as specified in the IEEE 802.15.4
standard. Notice that one device is capable of capturing data on one channel at a time. Simultaneous
multiple-channel capture is supported by using a number of ubisys IEEE 802.15.4 devices, each
operating on a different channel. Diversity capture is supported by using more than one ubisys IEEE
802.15.4 stick on the same channel.
- have to search for the channel the network is currently using. This is a must-have to observe frequency
hopping systems like WirelessHART and useful for debugging frequency-agile systems like ZigBee PRO
and ZigBee RF4CE
- On-board MCU: Advanced 32-bit ARM micro-controller running at 48MHz with 64KB SRAM powerful
enough to capture and buffer up to 128 packets (each comprising up to 127 bytes) until they are
delivered to the host computer. Makes you not lose any packet due to buffer overruns, interrupt latencies
or USB bus latencies in contrast to products based on slow 8-/16-bit controllers with
limited RAM (typically 8KB)
- On-board PHY: Texas Instruments CC2520
- On-board meandered inverted-F antenna
- USB 2.0 full-speed device, bus-powered. Power consumption: 50mA in active mode. Thus, can be
plugged into any USB port, even into passive hub ports, such as those integrated into keyboards
- Complies with Microsoft® RNDIS specification and is compatible with standard, pre-installed Windows
drivers. Appears as a network adapter in device manager
- Creates ZigBee Encapsulation Protocol Version 2.0 Frames (ZEPv2), which can be immediately
-in dissectors. Includes channel information, link quality indication (LQI),
received signal strength indication (RSSI) and a sequence counter
- Wireshark dissectors include: ZigBee, ZigBee PRO, ZigBee Green Power, 6lowpan. Wireshark can be
extended with dissectors, including dissectors for your own proprietary protocols based on the IEEE
802.15.4 MAC
- Supports on-the-fly decryption of encrypted ZigBee network traffic (APS and NWK security)
- Exploit the networking capabilities of Wireshark to gather the data captured by a remote machine
- Create capture files and send them to colleagues, who can review the capture logs in Wireshark
- More convenient than Ethernet-based capture devices when used with mobile notebook computers etc.
- Extensible and future-proof design: Firmware updates via USB
- Supported on 32- and 64-

5www.ubisys.de

4. Installation Microsoft Windows
Download and install the Wireshark software from http://www.wireshark.org. The software installer
package also includes WinPcap, a high-speed capture driver.
Download the ubisys IEEE 802.15.4 Wireshark USB stick driver package from here:
http://www.ubisys.de/engineering/download-drivers.html.
Extract the files in the driver package into any folder on your hard disk.
Plug the device into any spare USB port on your PC. Windows will ask you for drivers. Point to the
path where the extracted driver package files are stored. Follow the instructions on the screen.
When you are done, verify that the device has been installed correctly by opening Windows Device
Manager. Your ubisys IEEE 802.15.4 device with Wireshark capture firmware should appear under the
network adapter section.
Figure 1: ubisys IEEE 802.15.4 Wireshark USB Stick in Windows Device Manager

6www.ubisys.de

We strongly recommend that you disable all network protocols that are linked with the new adapter in
order to reduce traffic on the USB bus and the amount of data captured by Wireshark. In order to do
so, open the adapter settings (via control panel, network connections).
Figure 2: Network Connections
Right- -up menu
that appears. Next, make sure that all protocol links are disabled.
Figure 3: Network Adapter Properties
You are done. Installation with recommended adapter settings is complete.
The device can be used for capturing packets now.

7www.ubisys.de

5. Installation Linux
Download and install the latest Wireshark software source code from http://www.wireshark.org and
compile it on your system, or simply use a pre-compiled package for your Linux distribution. A
variety of Linux distributions and package managers is available, and we cannot provide
information for all of them. But the general steps are the same or at least very similar. If you use
debian or ubuntu Linux, you can download and install the pre-compiled package using the Advanced
Packaging Tool. You need administrator privileges for installation.
# sudo apt-get install wireshark
Next, you need to add a suitable driver for the ubisys IEEE 802.15.4 Wireshark USB stick. Prepare
your system for building kernel modules by downloading and installing the kernel headers that have
been used to build your kernel, compiler tool-chains etc.
# sudo apt-get install linux-headers-$(uname –r) linux-libc-dev kernel-package
You are also going to need the kernel sources, since ubisys provides a patch to the rndis_host.c driver
module. The community patch and accompanying shell script have both been provided by Marcus
Ihde-Meister and have been tested by ubisys on different hardware platforms.
First, determine your kernel version using:
# uname –r
2.6.32-5-powerpc64
In this example, this is a 2.6 kernel. Substitute 2.6 with whatever is returned by uname r up to the
major release number.
# cd /usr/src
# sudo apt-get source linux-source-2.6
This will create a linux-xxx subdirectory with the complete, patched kernel sources under /usr/src.
Download and extract the ubisys IEEE 802.15.4 Wireshark USB stick driver package for Linux, which
is provided as a gzip-compressed tar-ball.
# cd
# wget http://www.ubisys.de/downloads/ubisys-m7b-rndis.tgz
# tar –xzf ubisys-m7b-rndis.tgz
This creates a directory called ubisys-m7b-rndis under your home directory. Now, copy the original
rndis_host.c file from your Linux source directory to this directory:
# cd ubisys-m7b-rndis
# cp /usr/src/linux-2.6_2.6.32/drivers/net/usb/rndis_host.c .
And apply the community patch:

8www.ubisys.de

# patch rndis_host.c rndis_host.c.patch
Notice: If certain hunks could not be applied, you should nevertheless continue to build.
Now, build the patched kernel module:
# make
This results in an output like this:
make -C /lib/modules/2.6.32-5-powerpc64/build/ M=/root/ubisys-m7b-rndis modules
make[1]: Entering directory `/usr/src/linux-headers-2.6.32-5-powerpc64'
CC [M] /root/ubisys-m7b-rndis/rndis_host.o
Building modules, stage 2.
MODPOST 1 modules
CC /root/ubisys-m7b-rndis/rndis_host.mod.o
LD [M] /root/ubisys-m7b-rndis/rndis_host.ko
Finally, install the modified kernel module:
# sudo make install
In case the module has been loaded previously, you must unload it first. You can use the tool lsmod to
check if the module is active and rmmod to remove active modules. If rndis_wlan is also loaded, you
have to unload it first, since it depends on rndis_host.
# lsmod
# sudo rmmod rndis_host
It is strongly recommended that you disable Internet Protocol version 4 and 6 bindings to that interface
to prevent any traffic being generated on the sniffer interface.
Read the section on how to configure the capture channel to make the device operational, here we
want to capture on channel 26:
# sudo ./ieee802154_options.sh –c 26
Now we need to check the interface that has been created for the capture device. Print the recent
kernel messages to identify the interface:
# dmesg
Creates an output like this:
...
[2446022.499686] rndis_host ieee802154 channel is 26
[2446022.502352] rndis_host 1-1.4:1.0: eth3: register 'rndis_host' at usb-0000:00:1d.7-
1.4, RNDIS device, 00:1f:ee:00:01:84
...
Now, bring the interface up, such that it can be used by Wireshark:
# sudo ifconfig eth3 up

9www.ubisys.de

In the interface list shown in Wireshark pick eth3 as the capture interface.
Tested on ubuntu 12.04, i686, Kernel 3.2.0-32 and debian 6.0.6, ppc64, Kernel 2.6.32-5.

10 www.ubisys.de

6. Setting the Channel for Capture Microsoft Windows
Your ubisys IEEE 802.15.4 USB stick with Wireshark sniffer firmware is capable of capturing packets
on any of the 16 channels in the 2.4GHz band, i.e. channels 11-26 according to the IEEE 802.15.4
standard. However, only one channel at a time can be captured. If you need to capture more channels
concurrently, you will need one USB stick per channel, i.e. 16 sticks if you want to capture packets on
all channels simultaneously, e.g. to analyze frequency hopping systems.
In order to select the channel for capture, open Windows Device Manager and right-click on your
ubisys IEEE 802.15.4 Wireless Adapter for Wireshark and switch to the advanced settings tab:
Figure 4: Network Adapter Properties, Advanced Settings
Select the IEEE 802.15.4 Channel property and set its value to the channel you want to capture, i.e.
any decimal value in the range 11-26.
You can change the setting at any time. However, the adapter will disconnect and reconnect, so any
live-capture currently in progress will be interrupted.

11 www.ubisys.de

7. Setting the Channel for Capture Linux
Use the ieee802154_options.sh shell script, which is included in the Linux driver tar-ball, to start
capturing IEEE 802.15.4/ZigBee frames on any of the 16 channels in the 2.4GHz band.
# sudo ./ieee802154_options.sh –c 26
. If you want to make sure the command has
been accepted, use dmesg to print the kernel message log and look out for a rndis_host message like
this one:
...
[349673.652872] rndis_host ieee802154 channel is 26
...
Now you can start Wireshark:
# sudo wireshark &
The channel is also shown in the ZigBee encapsulation Protocol dissector:
c
Figure 5: Wireshark Capturing ZigBee Traffic on a PowerMac G5 Running Debian Linux 6.0.6 for PowerPC 64-bit

12 www.ubisys.de


13 www.ubisys.de

8. Using Wireshark for IEEE 802.15.4 Captures (Quick Introduction)
Start Wireshark to begin a new live-capture.
Figure 6: Wireshark Welcome Screen
Notice that the interface list includes the ubisys IEEE 802.15.4 capture device. If it does not appear on
your system and you recently installed the driver, please restart the packet capture driver (Winpcap),
first. You can either restart your computer or terminate Wireshark and then run the following commands
from a command prompt with elevated user access rights (run as administrator):
C:\WINDOWS\system32>net stop npf
C:\WINDOWS\system32>net start npf
Click on the ubisys USB IEEE 802.15.4 Capture Device for Wireshark item to begin a new live-
capture. The welcome screen disappears and a capture log appears.

14 www.ubisys.de

Figure 7: Wireshark Live-Capture in Progress...
You can select any of the captured packets while the live-capture is still in progress. Two detail
sections are available with decoded information as well as raw binary data:

15 www.ubisys.de

Figure 8: Dissector and Raw Binary Detail Views
Notice that the IEEE 802.15.4 frame is encapsulated in a ZEPv2 frame, which is transferred via
UDP/IP, and Ethernet (RNDIS). The ZEP frame includes channel number information and an LQI value
derived from individual correlation and RSSI values.

16 www.ubisys.de

Individual RSSI and LQI correlation values are available in the FCS field. Notice that this field is in
CC2420 format, i.e. the frame check sequence is not the value actually transmitted over the air. Instead
of the 16-bit CRC, there is only one bit that determines whether the FCS was correct. The remaining
Figure 9: Decoded IEEE 802.15.4 Packet with RSSI and Correlation Values

17 www.ubisys.de

Figure 10: Example of a ZigBee PRO Link Status Frame

18 www.ubisys.de

dissector view. The raw binary packet data will then be highlighted in the bottom area of the window.
Figure 11: Raw Binary Packet Data
Notice that Wireshark is a powerful tool with various filtering capabilities, capture options etc. Please
refer to the Wireshark documentation for a complete coverage of all features, including remote capture,
merging capture files, etc.

19 www.ubisys.de

9. Using Wireshark to Analyze Encrypted ZigBee PRO Traffic
You can use Wireshark to decrypt ZigBee PRO traffic on-the-fly. Both, secure NWK and APS frames,
can be dissected, as well as ZigBee Green Power.
To set the AES-CCM* security level according to your particular network setup, open the Preferences
for the ZigBee protocol. From the Edit menu, choose Preferences and expand the Protocols section.
Locate and lect the appropriate security level. For example a ZigBee Home
Automation Network is going to use security level 5, which means AES-128 encryption and 32-bit
message integrity code.
Figure 12: ZigBee NWK Preferences in Wireshark
For a ZigBee home automation network, you may use the default Trust Center link key
as long as it has not
been changed via commissioning k security setup. Notice
that the label is used to identify which key has been used by Wireshark to decode the frame.
Figure 13: Entering a ZigBee link or network key
Once you have entered the key, Wireshark is able to decrypt the Transport Key APS command.
Now, open the network for new devices, i.e. permit joining, and let a device join the network to trigger
transmission of the transport key command from the trust center to the joining device.

20 www.ubisys.de

Figure 14: Transport Key Command in ZigBee PRO Home Automation
Check the contents of the Transport Key command to obtain the current network key. In the present
example, the standard network key is 000102030405060708090a0b0c0d0e0f and can be added to
the pre-configured keys just like the Trust Center link key. Depending on the version of Wireshark you
are using, the software is also capable of learning the key automatically.