06. Supported Software

PyCatsniffer tool

This is the main tool to be used with the CatSniffer. It was developed by us to be used with Command Line Interface (CLI) to communicate with the Sniffer_fw_CC1352P_7 firmware. You can upload the required firmware with our Catnip Tool.

PyCatSniffer Tool

Features

• This tool actually supports the next protocols:
  • Bluetooth Low Energy (BLE)
  • IEEE 802.15.4
  • ZigBee
  • Thread
• 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.

Terminal output after installing requierments

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
• catsniffer-lora.lua

To copy the dissectors content we need to:

• Open Wireshark
• Help > About Wireshark > 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 (4.4 folder in our case)
• Restart Wireshark

Adding Wireshark dissectors

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

You can use the command python .\cat_sniffer.py --help to list the available commands of the tool.

Terminal output for help command

Protocols - protocols

python cat_sniffer.py protocols

Terminal output for protocols command

This command show the available protocols and description about the supported channels. The command show a table with the following 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

Terminal output for help on the sniff command

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.

Note

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

Example Calls

Note

$SERIAL_PORT will be depending on your OS

Commandpython3 cat_sniffer.py sniff $SERIAL_PORT -v Description: Default sniffing, BLE, channel 37 and with verbose output

Command: python3 cat_sniffer.py sniff $SERIAL_PORT -ch 39 -df Description: BLE, channel 39 and dump a pcap file with different BLE channel

Command:python3 cat_sniffer.py sniff $SERIAL_PORT -phy 0 -ch 39 -ff -ws Description: BLE, channel 39, and pipeline to communicate with Wireshark

Command: python3 cat_sniffer.py sniff $SERIAL_PORT -phy 1 -ch 11 -pf -df -dfn test.pcap Description: Dump a pcap file, hex file with custom name and IEEE 802.15.4 protocol

Command: python3 cat_sniffer.py sniff $SERIAL_PORT -df -pf -ff -ws Description: Dump a pcap file, hex file, verbose mode and show the packets on wireshark

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.

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.

Cativity

CativityDetector is a tool designed to analyze channel activity in Zigbee networks. It uses a CatSniffer device to monitor Zigbee channels, captures packets, and displays data related to network activity. The tool also provides graphical representations of the activity, helping users analyze the traffic over various Zigbee channels.

Functionality

• Sniffing Zigbee Channels: The tool listens to Zigbee channels (11 to 26) and collects packet data. It can either hop between channels automatically or remain fixed on a user-specified channel.
• Channel Hopping: The tool hops between Zigbee channels with a default interval of 3.5 seconds. It collects and analyzes packet data for each channel.
• Data Collection: As packets are received, the tool processes them using the Sniffer class, which decodes the Zigbee frames. It uses the TISnifferPacket class to handle packet payloads.
• Graphing Activity: The tool visualizes the channel activity using the Graphs class. It continuously updates the graph based on the number of packets received for each channel.
• Topology: Show the network childs of the network as the packet will be detected.
• Threading: The tool runs two background threads:
  • One for handling the channel hopping and activity collection.
  • One for updating and displaying the graphical representation of the channel activity.
• Logging: The tool logs key events and errors to both the console and a log file (catbee.log). The default logging level is set to "WARNING", but this can be adjusted in the logging configuration.

Installation

To use CatitivityDetector, yo must have the required dependencies installed. You can install them with pip:

pip install -r requirements.txt

You will also need to connect the CatSniffer device to your computer, as it is the primary hardware used by this tool.

Usage

The tool is used via the command line:

python cativity.py catsniffer_path [options]

Options:

• catsniffer: The serial path to the CatSniffer device. The default path is automatically detected.
• channel: The Zigbee channel to start sniffing on. If not provided, the tool will hop through channels 11 to 26.
• topology: Show the topology of the network.

Note: the automatic port detection function may fail if the operating system does not recognize the vendor ID of the board. If two CatSniffer boards are plugged in, the software will return the first port only.

Examples

python cativity.py

This command will run Cativity with default settings, automatically detected CatSniffer port and channel hopping enabled.

python cativity.py COM90 --channel 25

This command will run Cativity with a explicit path and fixed channel.

python cativity.py COM90 --channel 25 --topology

This command will map the network topology for a fixed channel.

Acknowledgements

Special thanks to @kevlem97 for the catbee repository, which served as the foundation for this project.

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.