Ubisys | IEEE 802.15.4 usb stic with wireshark firmware | User manual | IEEE 802.15.4 Wireshark USB Stick (PDF, 26 pages, 5,3MB)
Add to my manuals29 Pages
advertisement
REFERENCE MANUAL
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
2 www.ubisys.de
2. Contents
4. Installation Microsoft Windows
6. Setting the Channel for Capture Microsoft Windows
7. Setting the Channel for Capture Linux
8. Using Wireshark for IEEE 802.15.4 Captures (Quick Introduction)
9. Using Wireshark to Analyze Encrypted ZigBee PRO Traffic
10. Multiple-Channel Capture and Diversity
Known issues with firmware versions 1.04 1.00
Known issues with firmware versions 1.03 1.00
3 www.ubisys.de
4
3. Features
-
Powerful IEEE 802.15.4 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,
ZigBee Green Power 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 64ems
-
Timing accuracy: Approximately one IEEE 802.15.4 PHY symbol period (16 micro-seconds) in the timestamps provided in the ZEPv2 header www.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
5 www.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
Rightthat appears. Next, make sure that all protocol links are disabled.
-up menu
6
Figure 3: Network Adapter Properties
You are done. Installation with recommended adapter settings is complete.
The device can be used for capturing packets now. www.ubisys.de
7
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: www.ubisys.de
8
# 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 www.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.
9 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.
10 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
Inst . 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
11
Figure 5: Wireshark Capturing ZigBee Traffic on a PowerMac G5 Running Debian Linux 6.0.6 for PowerPC 64-bit 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 livecapture. The welcome screen disappears and a capture log appears.
12 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:
13 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 and a time-stamp
1
that is accurate to approximately one PHY symbol period (16 microseconds).
The time-stamp, despite being specified as an absolute NTP time-stamp, is rather meant as a relative time-stamp, which starts at a fixed time, e.g. January 1, 2012 in firmware revision 1.03 and below, or
January 1, 2015, 00:00h in firmware revision 1.04, when the device is powered. The underlying hardware timer hosts a 32-bit register incrementing at a rate of 62.500Hz (corresponding to the PHY s symbol frequency), which results in a roll-over after approximately 19 hours of operation, when the time-stamp restarts at its pre-configured absolute start-time again.
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
1
The time-stamp is valid in firmware versions 1.04 and above
14 www.ubisys.de
Figure 9: Decoded IEEE 802.15.4 Packet with RSSI and Correlation Values
15 www.ubisys.de
Figure 10: Example of a ZigBee PRO Link Status Frame
16 www.ubisys.de
dissector view. The raw binary packet data will then be highlighted in the bottom area of the window.
17
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. 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
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. For distributed security networks (like ZigBee Light Link) use the appropriate
2
global distributed security trust center link key, e.g. for uncertified products use the wellknown key D0:D1:D2:D3:D4:D5:D6:D7:D8:D9:DA:DB:DC:DD:DE:DF. For other profiles, refer to the
Notice that the label is used to identify which key has been used by
Wireshark to decode the frame. Notice that you may enter as many keys as you wish, for example the default Trust Center link-key, the distributed security link-key and any number of pre-configured linkkeys (e.g. derived from installation codes) that you require in addition.
Figure 13: Entering a ZigBee link or network key
18
2
It is not recommended to use the confidential distributed security link key, i.e. the key used in certified devices, unless you are doing so in a secure production facility or laboratory environment for end-product testing in accordance with all contracts, terms and conditions your company has accepted and signed. www.ubisys.de
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.
19
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. www.ubisys.de
Figure 15: Wireshark ZigBee pre-configured keys
20 www.ubisys.de
10. Multiple-Channel Capture and Diversity
It is possible to capture traffic on multiple channels simultaneously. This might be necessary to observe frequency hopping and frequency-agile systems. For each channel, a distinct ubisys IEEE 802.15.4 stick with Wireshark Firmware is required. Thus, to cover all channels in the 2.4GHz band, sixteen sticks are required, which can be ordered as a bundle. Additional sticks are also beneficial to mitigate the effects of multipath fading in indoor environments. In this case tune more than one stick to the same channel.
While you could use multiple instances of Wireshark in order to run multiple captures and then merge the captures files, it is often more convenient to group all sticks and run a single capture (on all sticks).
21
Figure 16: Selecting multiple interfaces for capture in Wireshark (here, five ubisys IEEE 802.15.4 USB Sticks) www.ubisys.de
22
Figure 17: Diversity capture with five Sticks. Certain nodes (e.g. 0xc6fa), only received by one out of five sticks.
The figure above shows the benefit of diversity capture. The tagged group of link status messages from node 0xbd2d is received by all sticks concurrently, as expected. But only one out of five sticks was able to receive a message from node 0xc6fa at the border of wireless range.
Notice: Simultaneous capture on multiple interfaces is inherently supported by later versions of
Wireshark as shown above. The information below remains available for reference, only.
This can be achieved with Windows built-in network bridge feature. Open the network connections view and select the ubisys IEEE 802.15.4 adapters you want to group. Right-click on one of them and select the Bridge Connections command from the context menu that appears. This will create a network bridge. www.ubisys.de
Figure 18: Network Bridge for Diversity or Multiple-Channel Capture
Edit the properties for the new connection and disable all protocols, as you have done for all the individual ubisys IEEE 802.15.4 adapters. You can add and remove other adapters from the group of bridged devices by adding or removing the check mark in the adapter selection area.
Figure 19: Network Bridge Properties
23 www.ubisys.de
24
11. Troubleshooting manage to solve the problem, feel free to contact ubisys support.
Make sure that the driver is properly installed
Make sure that you have disabled all networking protocols
Make sure that the ubisys 802.15.4 networking adapter is enabled and has not been disabled
Make sure that no enterprise security software, firewall or anti-virus program blocks the network adapter. Contact your IT department if you are uncertain. Some of these applications require the IT administrator to authorize new hardware, in particular network adapters, before they are allowed to operate normally
Make sure that there is actually wireless traffic on the channel that you have selected
If you are trying to capture data from a single transmitter, you might be in a dead-spot (unlikely, but still)
Make sure that there is no interference that prevents the sniffer from receiving data
Unplug the USB stick and plug it in again, then restart packet acquisition
11.1.
Known issues with firmware versions 1.04 1.00
Problem: When the host computer is put into sleep mode while the device is connect, this may cause a blue-screen in the Windows RNDIS driver a few seconds (about 15 to 30) after the computer is awake again.
Work-around: Detach the USB stick before entering sleep mode or before waking the computer. This will be fixed in a future firmware release.
11.2.
Known issues with firmware versions 1.03 1.00
Problem: The time-stamp in the ZEPv2 frame is either fixed at zero or not always maintained correctly.
Solution: Please upgrade to firmware revision 1.04 or above.
Problem: Occasionally the capture could get stuck. The statistics show incoming traffic (the received packet count increases), but the incoming frames are not delivered to the host PC.
Solution: Please upgrade to firmware revision 1.04 or above. www.ubisys.de
12. Physical Dimensions
Figure 20: USB Stick with on-board PCB antenna
25 www.ubisys.de
13. Ordering Information
The following tables list the product variants available. Use the specified order code for your orders.
Please contact ubisys support if you require any customization.
Case
Black
Light gray
Transparent
Firmware variant
Wireshark/RNDIS
Wireshark/RNDIS
Wireshark/RNDIS
Product Number
U0101-010110-02
U0101-010210-02
U0101-010310-02
Order Code
9010
9027
9034
26 www.ubisys.de
27
14. Declaration of Conformity
We ubisys technologies GmbH, Am Wehrhahn 45, 40211 Düsseldorf, Germany declare under our sole responsibility that the ubisys IEEE 802.15.4/ZigBee USB Gateway stick with RNDIS/Wireshark declaration relates are in conformity with the following directives and standards:
Directive/Standard
1995/5/EC
2004/108/EC
2006/95/EC
2002/96/EC
2002/95/EC
EN 300 328
EN 300 440
EN 301 489
IEEE 802.15.4
Düsseldorf, Germany
Place of issue
Dr.-Ing. Arasch Honarbacht
Full name of Authorized Signatory
Description/Scope
Radio and Telecommunications Terminal Equipment Directive (R&TTE)
Electromagnetic Compatibility Directive (EMC)
Low Voltage Directive (LVD)
Waste Electrical and Electronic Equipment Directive (WEEE)
Restriction of Hazardous Substances Directive (RoHS)
ERM; Wideband transmission systems; 2.4 GHz ISM band
ERM; Radio equipment to be used in the 1 GHz to 40 GHz frequency range
EMC
IEEE Standard 802 Part 15.4: Low-Rate Wireless Personal Area Networks (LR-WPANs)
October 16, 2012
Date of issue
Managing Director, Head of Research & Development
Title of Authorized Signatory
Seal Signature www.ubisys.de
15. Revision History
Revision
1.0
1.1
1.2
1.3
1.4
Date
25/09/2011
17/10/2011
18/10/2011
15/12/2011
16/10/2012
1.5
1.6
1.7
20/12/2012
16/06/2014
05/12/2014
1.8 02/18/2015
Remarks
Initial Public Version
Added ZigBee PRO Encrypted Traffic Chapter
Added Multiple-Channel Capture Chapter
Minor corrections
Minor corrections. Added diversity capture example and updated multiple capture interface information.
Conformity statement included.
Added instructions for Linux
Added instructions for manually restarting Winpcap
Added ZigBee Green Power to the list of protocols
-of-the and added a trouble-shooting section.
Included information about timing accuracy in firmware revision 1.04 and above and a list of known issues with various firmware versions. Added a note on distributed security Trust Center link-keys and pre-configured linkkeys.
28 www.ubisys.de
16. Contact
UBISYS TECHNOLOGIES GMBH
HARDWARE AND SOFTWARE DESIGN
ENGINEERING AND CONSULTING
AM WEHRHAHN 45
40211 DÜSSELDORF
GERMANY
T: +49 (211) 54 21 55 - 00
F: +49 (211) 54 21 55 - 99 www.ubisys.de [email protected] [email protected]
29 www.ubisys.de
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Related manuals
advertisement