sudo usermod -a -G dialout $USER

newgrp dialout

This is the main tool to be used with the CatSniffer. It was developed by us to be used with the 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

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

Requirements

To install the requirements, we first need to have Python 3 installed and the environment variable to call Python. To initialize, first we need to install the dependency packets from the requirements.txt.

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

Terminal output after installing requirements

Setting up the Environment

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 shows the available protocols and descriptions about the supported channels. The command shows a table with the following information about the protocol support:

• Index: The index value to use 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.

Sniffer - sniff

python cat_sniffer.py sniff --help

Terminal output for help on the sniff command

These 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. The script will automatically find this value; it is only necessary to specify it if you are working with more than one CatSniffer.
• address (experimental): This value is the MAC address of the device whose connection we want to follow.

Options

• phy: This value sets the phy value, as referred to in the protocols section correspond to the index value.
• channel: This is the value from the channel to sniff; these index values are shown in the protocols section.

Output Options

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

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

Load the corresponding sniffle_cc1352p_7 firmware to your board’s CC1352 chip. You can load the precompiled firmware using our Catnip Uploader Tool, you can learn how to do that here.

Loading Sniffle with Catnip

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

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.

Sniffle Repository

After downloading everything, go to the terminal and navigate to the location where you saved the repository files. And then go into the ‘python_cli’ folder.

Python CLI Folder

Here you can run any of the available scripts.

Available Commands

In the Sniffle repository, you can find the ‘Usage Examples’ section on their readme to get a good idea of 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.

sniffer_receiver.py

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

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

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).

Personal Extcap Path

Creating symbolic links allows easy updates to the files.

• Navigate to the path where you saved the Sniffle files
• Create the symbolic link to the Extcap Personal directory
  • For Windows:

mklink "%APPDATA%\Wireshark\extcap\sniffle_extcap.py" "C:\{PATH}\{TO}\Sniffle\python_cli\sniffle_extcap.py"

• For Linux:

ln -s $(pwd)/python_cli/sniffle_extcap.py ~/.local/lib/wireshark/extcap/sniffle_extcap

This way, you can pull any updates in the Sniffle folder, and the changes to the sniffle_extcap.py will be directly made.

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

Wireshark Refresh Option

Sniffle Interface in Wireshark

If you can see the Sniffle BLE sniffer interface, you are ready to start using it with Wireshark.

This step is needed for Linux installation. Open the Terminal and run the following commands:

chmod +x ~/.local/lib/wireshark/extcap/sniffle_extcap

The structure should be something like:

~/.local/lib/wireshark/extcap/
└── sniffle_extcap  -> /path/to/Sniffle/python_cli/sniffle_extcap.py

When selecting the “Sniffle BLE sniffer” interface in Wireshark for the first time, a configuration window will appear where you must specify the CatSniffer port (for example, /dev/ttyACM0 or COM85).

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

• 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 children 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.

To use CativityDetector, you must have the required dependencies installed. You can install them with:

pip install -r requirements.txt

Cativity Requirements

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.

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

To be able to work with our board in Wireshark, we need to set up the CatSniffer dissectors. Before, we used .lua dissectors. We now have precompiled C dissectors that work much better. The C dissectors can be found on the CatSniffer-Wireshark repository. These dissectors are primarily for development.

CatSniffer-Wireshark Repository

Go to the Releases:

Releases

Download the version matching the operating system on your computer. Locate the downloaded dissectors on your computer. There should be two files catsniffer and catsnifferx1262. The first is used for IEEE 802.15.4, and the latter is used for LoRa.

• In Wireshark, go to Help > About Wireshark > Folders
• Click the “Personal Plugins” path and confirm the creation of the directory.
• You can manually create the subfolder epan using the file manager or by running the command on the terminal:

mkdir "%APPDATA%\Wireshark\plugins\4.4\epan"

On Linux, create the epan subfolder for the required version from the terminal:

mkdir -p ~/.local/lib/wireshark/plugins/4.4/epan

Copy the unzipped downloaded dissector to the epan folder; you might require administrator privileges to do so.

Dissector Folder

We now need to set both dissectors in Wireshark. Open Wireshark and go to Edit > Preferences > Protocols > DLT_USER. Click on Edit… and, using the plus sign, add another entry with the following values:

catsniffer

• DLT: User 0 (DLT=147)
• Payload dissector: catsniffer_rpi
• Header size: 0
• Trailer size: 0

catsnifferx1262

• DLT: User 0 (DLT=147)
• Payload dissector: catsnifferx1262_rpi
• Header size: 0
• Trailer size: 0

User DLTs Table

Click OK, Apply, and then OK again.

Only for Linux installations tun the following command in the Terminal:

chmod +x ~/.local/lib/wireshark/plugins/4.4/epan/*.so

REST WIRESHARK TO MAKE IT WORK!

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.

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

TI's Packet Sniffer Webpage

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

TI's Packet Sniffer Webpage

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 as a .zip file; go to the route where it was downloaded and extract the files.

Smart RF Zip

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

Smart RF Executable

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.

Smart RF Installer

To use this software with your CatSniffer first you will need to load the SerialPassthroughwithboot_RP2040_v1.1.uf2 to the RP2040 and the sniffer_fw_CC1352P_7_v1.10.hex on the CC1352. 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 into your PC using the provided USB-C cable.

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

Smart RF Scanning for 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.

Device Configuration Button Close Up

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.

Device Configuration Window

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.

Radio Options Window

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

Start Button

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.

Smart RF Running

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 is a network packet analyzer. A network packet analyzer presents captured packet data in as much detail as possible.

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. We recommend using the latest stable version of Npcap. Optionally, you can use the Npcap version shipped with the installer.
6. Follow the last steps on the installer, and you are done with this section.

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 in the ‘Target’ space, modify the path by 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.

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 paid software and so requires a subscription to use.