06. Supported Software

Smart RF Packet Sniffer 2

SmartRF Packet Sniffer is a PC software application that can display and store radio packets captured by a listening RF device. The capture device is connected to the PC via USB. Various RF protocols are supported. The Packet Sniffer filters and decodes packets and displays them in a convenient way, such as Wireshark for the CC13xx and CC26xx devices.

Version:

• For CatSniffer v3.X you can use the latest version, 1.10 at the moment.
• For CatSniffer v1.X and v2.X you will need to use version 1.8.0. To download earlier versions of the software you need a Texas Instruments account.

Download & installation

If you are going to use SmartRF Packet Sniffer alongside Wireshark, we recommend you install that first. This way the Packet Sniffer installer will recognize Wireshark on your system and configure it.

To download this software you will need to log in to a Texas Instruments account or create a new one if you do not have one.

1. Go to the download link for the software: PACKET SNIFFER

2. Go to the calculation tool section and click on the ‘Download option’ button.

3. A menu will open and display a download link for the latest version.

4. If you need an earlier version you will need to click on the ‘View all versions’ link. And select the correct one for you.

5. The program will be downloaded on a .zip file, go to the route where it was downloaded and extract the files.

6. After the files have been extracted, execute the Setup_SmartRF_Packet_Sniffer2_1.x.x.exe file as administrator.

8. During the installation if Wireshark was installed correctly first, the installer will prompt you with an option to copy the dissector plugins to the Wireshark installation. Accept this and continue with the installation.

Using SmartRF Packet Sniffer 2

To use this software with your CatSniffer first you will need to load the SerialPassthroughwithboot.ino and the sniffer firmware (this one is different for every cc1352 chip) to your board. Depending on which version of the board you have the process will change slightly. You can check the Loading Firmware section of this Wiki if you need any help. If you have loaded both firmwares to your board you can continue.

1. Plug your CatSniffer to your PC using the provided USB-C cable.

2. Run SmartRF Packet Sniffer 2. The software will begin to search for compatible devices.

3. When the search finishes if a compatible device was detected, the option ‘Device Configuration’ will be enabled, click there and a new window will open.

4. In the device configuration window you will see the information for the connected device. Check the box for using the board. Now you can click on the ‘Configure’ button.

5. A new window called ‘Radio Options’ will open. In this window you can select the protocol and frequency band you want to sniff. Click okay when you have configured it to your preferences.

6. You will be taken back to the ‘Device configuration’ window. You can now click on the ‘Start’ button to start sniffing.

7. You will be taken to the original window, and you will see the status section change to Running and Connecting. You will also see the number of incoming and outgoing packages.

8. If you are going to use Wireshark with SmartRF Packet Sniffer, you will need to go to Options > Data Output and then check that the option for ‘Use Pipe’ is selected.

Wireshark

Wireshark is a network packet analyzer. A network packet analyzer presents captured packet data in as much detail as possible.

Download and Install

1. Go to the Wireshark webpage and to the ‘Get Started’ section: Wireshark
2. Download and run the latest version.
3. Preferably select the default installation path.
4. Install ALL the additional components requested.5
5. We recommend using the latest stable version of Npcap. Optionally, you can use the Npcap version shipped with the installer.
6. Follow the last stamps on the installer and you are done with this section.

Using Wireshark with SmartRF Packet Sniffer 2

1. First we will need to verify that the Texas Instruments SmartRF Packet Sniffer plugins were installed correctly on Wireshark. Click on the plugins tab on Wireshark and check if the following plugins were installed:

   • ti802154ge-x(86/64)-2x.dll
   • tirpi-x(86/64)-2x.dll
   • ti-ble-packet-info-x(86/64)-2x.dll

2. Press the Windows key, type Wireshark, right-click on the Wireshark icon and then click on ‘Open file location’

3. Locate the Wireshark.exe file, right click on it and then click on ‘Create a shortcut’.

4. A shortcut will be created on your desktop. Right-click on the shortcut and click on properties. Go to the shortcut tab and on the ‘Target’ space modify the path adding -i\\.\pipe\tiwspc_data -k.

5. Click apply and then ok.

6. Open Packet Sniffer as mentioned in the previous section and then run Wireshark from your shortcut.

7. You will now see the packages being sniffed.

PyCatsniffer tool

This tool uses Command Line Interface (CLI) to communicate with the Sniffer_fw_CC1352P_7 firmware that you can upload with out catnip tool.

Features

• This tool actually supports the next protocols:
  • Bluetooth Low Energy (BLE)
  • IEEE 802.15.4
  • ZigBee
• Multi platform support
• Direct wireshark communication with PIPE's
• Dump the received packets in:
  • Pcap Format
  • Hex Format

Getting Starter

Requirements

To install the requirements we need first Python 3 installed and the environment variable to call python. To initialize first we need to install de dependencies packets from the requirements.txt.

Note

We recommend use virtual environment to avoid dependencies errors.

To install de requirements run the next command: pip install -r requirements.txt If all the requirements are satisfactory installed we can proceed to running the script.

Setting up the Environment

Wireshark

Set the Dissector

We need to copy the three .lua files dissector to be able to read the information.

.dissectors:
├── catsniffer-blepi.lua
├── catsniffer-register.lua
└── catsniffer-rpi.lua

To copy the dissectors content we need to:

• Open Wireshark
• Wireshark > About > Folders
• Double click on the Personal Lua Plugins path (this create the folder path)
• Copy the content inside the dissectors folder into the Personal Lua Plugins folder
• Restart Wireshark

Configure the DLT 147 value

To use wireshark and show the information we need to configure the USER DLT value to redirect the sniffer packet to the dissectors files.

• Open Wireshark
• Preferences > Protocols > DLT_USER
• Click on the Edit... button
• Create new entry
• The entry value are defined as:
  • DLT: User 0 (DLT=147)
  • Payload dissector: catsniffer_rpi
  • Header size: 0
• Click in Ok button
• Click in Ok button

Available Commands

List Devices - ld

$ python cat_sniffer.py ld

This commands show the available com ports, running this command we can view what port is available and if our CatSniffer is connected.

Protocols - protocols

$ python cat_sniffer.py protocols

This command show the available protocols and description about the supported channels.

The command show a table with the information about the protocol support.

• Index: The index value to used when a sniff command is called.
• Protocol: Protocol name
• Frequency: The base frequency of the protocol
• Channel Range: Show the relation of the channel and the frequency, the index value is used in the sniff command to select the channel to sniff.

Note

The Channel Range is showed in the min value and max value of the channel range available in the protocol.

Sniffer - sniff

$ python cat_sniffer.py sniff --help

This commands initialize the sniff communication with the board, to start the sniffing the command requires some initial configuration.

Arguments:

• comport: This value is the path to the board serial com
• address (experimental): This value is the MAC address of the device to follow the connection

Options

• phy: This value set the phy value, as refers in the [protocols section] correspond to the index value.
• channel: This is the value from the channel to sniff, this index values are showed in the protocols section.

When a different phy is selected, we need to specify the channel to sniffing.

Output Options

• verbose: Show the sniffed packets in the console.
• dump: Is a flag value, if we write this will generate a dump hex file
• dump-name: Is the flag value, if we write this with a value change the default dump name.
• pcap: Is a flag value, if we write this will generate a dump pcap file
• pcap-name: Is the flag value, if we write this with a value change the default dump name.
• fifo: This flags set a pipe line to communicate with wireshark
• fifo-name: Set the name of the pipe
• wireshark: This open a wireshark in the same thread of the script and open automatically the fifo. (Require the -ff option to open)

Important

If your are in windows to call Wireshark from the terminal you need to set the installation path to the Environmental Variables

Examples calls

$SERIAL_PORT will be depending on your OS please check your serial port name by:

$ python cat_sniffer.py ld

Default sniffing

• Protocol: BLE
• Channel: 37
• Verbose

$ python3 cat_sniffer.py sniff $SERIAL_PORT -v

Dump a pcap file with different BLE channel

• Protocol: BLE
• Channel: 39
• Dump File

$ python3 cat_sniffer.py sniff $SERIAL_PORT -ch 39 -df

Default sniffing

• Protocol: BLE
• Channel: 37
• Wireshark

$ python3 cat_sniffer.py sniff $SERIAL_PORT -phy 0 -ch 39 -ff -ws 

Dump a pcap file, hex file with custom name and IEEE 802.15.4 protocol

$ python3 cat_sniffer.py sniff $SERIAL_PORT -phy 1 -ch 11 -pf -df -dfn test.pcap

Dump a pcap file, hex file, verbose mode and show the packets on wireshark

$ python3 cat_sniffer.py sniff $SERIAL_PORT -df -pf -ff -ws

Sniffle

Sniffle is a sniffer for Bluetooth 5 and 4.x (LE) using TI CC1352/CC26x2 hardware.

Sniffle has a number of useful features, including:

• Support for BT5/4.2 extended length advertisement and data packets

• Support for BT5 Channel Selection Algorithms #1 and #2

• Support for all BT5 PHY modes (regular 1M, 2M, and coded modes)

• Support for sniffing only advertisements and ignoring connections

• Support for channel map, connection parameter, and PHY change operations

• Support for advertisement filtering by MAC address and RSSI

• Support for BT5 extended advertising (non-periodic)

• Support for capturing advertisements from a target MAC on all three primary advertising channels using a single sniffer. This makes connection detection nearly 3x more reliable than most other sniffers that only sniff one advertising channel.

• Easy to extend host-side software written in Python

• PCAP export compatible with the Ubertooth

• Wireshark compatible plugin

Using Sniffle

1. Load the corresponding ‘sniffle.hex’ firmware to your board’s CC1352 chip. You can find the precompiled hex file on our repository.

2. Once the Sniffle firmware has been loaded to the board, it is ready to be used with the Sniffle scripts.

3. We recommend you clone the Sniffle Repository so you have all the latest versions of the tools. Alternatively you can download the .zip file from the repository.

4. After downloading everything, go to the terminal and navigate to the location where you saved the repository files.

5. Go into the ‘python_cli’ folder.

6. Here you can run any of the available tools.

7. In the Sniffle Repository you can find the ‘Usage Examples’ section on their readme to get a good idea on the type of things you can do with the tools. You can see here the most basic use of the ‘sniffer_receiver.py’ tool. By just running the sniffer_receiver tool and specifying the COM port for our CatSniffer.

You can refer to the Sniffle Repository to see all the different options you can configure while using the tools.

Using Sniffle with Wireshark

Sniffle includes a Wireshark plugin that makes it possible to launch Sniffle automatically from the Wireshark GUI by selecting the 'Sniffle' capture interface.

1. To install the Sniffle plugin, first find the location of your Personal Extcap folder in the 'About Wireshark' dialog (Help > About Wireshark > Folders > Personal Extcap path).
   • On Unix systems, this folder is typically located at ~/.config/wireshark/extcap.
   • Under Windows, it can be found at %USERPROFILE%\AppData\Roaming\Wireshark\extcap.

2. Copy the following files from the python_cli directory into your Personal Extcap folder:

• python_cli/pcap.py
• python_cli/packet_decoder.py
• python_cli/sniffle_hw.py
• python_cli/sniffle_extcap.py
• python_cli/sniffle_extcap.bat (Windows only)

• On Unix systems, ensure that the main plugin script is marked executable:

  chmod +x ~/.config/wireshark/extcap/sniffle_extcap.py

• On Windows, it may be necessary to edit sniffle_extcap.bat to specify the location of the python interpreter if the installation directory is not included in the PATH, e.g.:

  @echo off C:\my_python_install\python.exe "%~dp0sniffle_extcap.py" %*

3. Once the plugin has been installed, restart Wireshark or choose Capture > Refresh Interfaces to enable the Sniffle interface.

4. Double click on the capture option for Sniffle BLE sniffer, and you will start seeing the sniffed packages.

Ubiqua Protocol Analyzer

Ubiqua Protocol Analyzer integrates decoders for leading IEEE 802.15.4-based protocols, including Zigbee, Thread, and 6LowPAN; with a wide range of analysis features to create a powerful, user-friendly, fast, and scalable debugging tool, tailored to help engineers through the different phases of the Internet of Things application development process. This is a paid software and so requires a subscription to use.