5. First time running FaultyCMD

Warning

If you are moving from previous CatSniffer firmware and tools, you will need to first upload an .uf2 file to the FaultyCat so FaultyCMD can recognize it.

Find the instructions here: How to update FaultyCat.

To start using FaultyCMD, you must:

• For Windows users, run a new terminal session in the same path as where the file faultycmd_vx.x.x.x.exe is located.
• For Linux /macOS / Window-with-Python start the virtual environment where you installed the package. See more information here: FaultyCMD Installation-Linux /macOS / Window-with-Python

catnip

You will see the main view of the CLI:

╭─ Electronic Cats - PWNLAB ───────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                      │
│        :=--             --=-       |                                                                                 │
│        -====-         -=====       |                                                                                 │
│        :===================-       |                                                                                 │
│         ===================:       |                                                                                 │
│    -   :==--===========--==-   -   |  catnip                                                                         │
│   -===:===-   :=====-   -==-.-=--  |  vX.X.X.X                                                                       │
│  --    ====-   :===-   -====    -- |  The air is full of data. Help yourself.                                        │
│  -=:   :===================-   .=- |                                                                                 │
│   ---=-- -===============-  -=---  |                                                                                 │
│   ---       --=======--        --  |                                                                                 │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: catnip [OPTIONS] COMMAND [ARGS]...

  CatSniffer: All in one catnip tools environment.

Options:
  -v, --verbose  Show Verbose mode
  -h, --help     Show this message and exit.

Commands:
  cativity    IQ Activity Monitor
  devices     List connected CatSniffer devices
  flash       Flash CC1352 Firmware or list available firmware images
  identify    Send identification command to CatSniffer device
  lora        LoRa SX1262 tools
  meshtastic  Meshtastic protocol tools
  restore     Restore CC1352 when bootloader is broken.
  sniff       Sniffer protocol control
  update      Check and update RP2040 firmware to match the latest release.
  verify      Verify CatSniffer device functionality

In the main view output, you can check the following:

• Local release search: Checks if firmware has been previously downloaded.
• Firmware download: Retrieves each required file from the official repository.
• SHA256 verification: Validates the integrity of each downloaded firmware.
• Final confirmation: Shows the installed release version and its publication date.

Checking the connected devices

Before performing any operation, it is recommended to verify that the system correctly detects the CatSniffer(s). To do this, run the command:

catnip devices

Important

If Catnip is not able to see the CatSniffer(s) connected, this may indicate there is a problem with the serial ports permission with your user. Please refer to sections installation of your operating system.

Each CatSniffer device exposes three serial ports with specific functions:

1. Cat-Bridge (CC1352): Main communication port.

   • Used for firmware flashing.
   • Data channel for protocol sniffing.
   • TI CC1352 chip control interface.

2. Cat-LoRa (SX1262): LoRa radio interface.

   • Communication with the Semtech SX1262 chip.
   • LoRa packet capture.
   • Radio parameter configuration.

3. Cat-Shell (Config): Configuration port.

   • Bootloader access.
   • Advanced device configuration.
   • Interactive command shell.

Example of expected output when having multiple CatSniffers connected:

                          Found 2 CatSniffer device(s)
╭───────────────┬─────────────────────┬───────────────────┬────────────────────╮
│ Device        │ Cat-Bridge (CC1352) │ Cat-LoRa (SX1262) │ Cat-Shell (Config) │
├───────────────┼─────────────────────┼───────────────────┼────────────────────┤
│ CatSniffer #1 │ /dev/ttyACM3        │ /dev/ttyACM4      │ /dev/ttyACM5       │
│ CatSniffer #2 │ /dev/ttyACM0        │ /dev/ttyACM1      │ /dev/ttyACM2       │
╰───────────────┴─────────────────────┴───────────────────┴────────────────────╯

Where:

• CatSniffer #1: First detected device, accessible as --device 1
• CatSniffer #2: Second detected device, accessible as --device 2

Note

Ports are automatically assigned by the operating system.

---

Available commands

Important

In multi-device configurations, it is essential to specify the device ID using the --device <ID> parameter in all subsequent commands to avoid ambiguity.

After initialization, the tool displays available commands.

Usage:

catnip <OPTIONS> <COMMAND>

Argument <OPTIONS>	Description
--verbose, or -v	Show verbose mode
--help, or -h	Show the help menu

Argument <COMMAND>	Description
cativity	IQ Activity Monitor for 802.15.4 networks (Zigbee/Thread)
devices	Lists connected CatSniffer devices
flash	Manages and flashes firmware on the CC1352 chip
identify	Sends an identification command to the device for visual identification
Sniffing subcommands	-
sniff ble	Sniffing BLE with Sniffle firmware
sniff zigbee	Sniffing Zigbee with Sniffer TI firmware
sniff thread	Sniffing Thread with Sniffer TI firmware
sniff lora	Sniffing LoRa with Sniffer SX1262 firmware
sniff airtag_scanner	Apple AirTag Scanner firmware
verify	Runs hardware functionality diagnostics
Meshtastics subcommands	-
meshtastic decode	Decrypt and decode a hex-encoded Meshtastic packet
meshtastic live	Live Meshtastic decoder - Capture and decode packets in real-time
meshtastic dashboard	Meshtastic Chat TUI - Beautiful terminal dashboard for Meshtastic
meshtastic config	Extract PSKs and config info from a Meshtastic JSONC config file
LoRa subcommands	-
lora spectrum	Live Spectrum Scanner for SX1262 - Real-time frequency spectrum analyzer

Firmware management

Catnip completely automates the process of downloading, verifying, and installing firmware on the CC1352 chip.

Usage:

catnip flash <OPTIONS> <FIRMWARE>

Argument <OPTIONS>	Description
--list, or -l	Display all the available firmwares images to flash
--device, or -d INTEGER	Device ID (for multiple CatSniffers). If not specified, the first device will be selected
--help, or -h	Show the help menu

Argument/Aliases <FIRMWARE>	Description
BLE	-
ble, or sniffle	Sniffle BLE sniffer
airtag-scanner	Apple Airtag Scanner
airtag-spoofer	Apple Airtag Spoofer
justworks	JustWorks scanner
Zigbee/Thread/15.4 (TI Sniffer)	-
zigbee	Texas Instruments multiprotocol sniffer
thread	Texas Instruments multiprotocol sniffer supporting Zigbee and Thread
15.4	Texs Instruments multiprotocol sniffer supporting 802.15.4
ti	Texas Instruments sniffer
multiprotocol	TI multiprotocol firmware
LoRa (RP2040)	-
lora-sniffer	LoRa Sniffer for Wireshark

Examples:

In the following command, we have selected a CatSniffer and flashed the Texas Instruments multiprotocol sniffer to sniff Zigbee traffic.

catnip flash --device 1 zigbee

The system accepts four methods to specify which firmware to flash:

1.Firmware flashing using aliases

Aliases are short names assigned to each firmware. This is the most convenient method. This method is easy to remember, requires less typing, and is less prone to typos.

Example:

catnip flash sniffle

2.Firmware flashing using partial names

Catnip can make partial matches of the firmware file name. This is useful when you do not remember the full name of the firmware; there is no need to remember specific aliases.

Example:

catnip flash sniffer_ti

3.Firmware flashing using full names

Exact specification of the firmware file name. Useful in automated scripts. The firmware full name can be read when you use the command catnip flash --list

Example:

catnip flash sniffer_ti_CC1352P_7_v1.0.hex

4.Firmware flashing using own firmware files (advanced)

Catnip allows flashing custom firmware files that are not in the official repository, as long as they are placed in the release directory and follow the expected format, or write the path where the custom firmware is located.

Example:

catnip flash --device 1 ~/PersonalProject/workspace/custom_firmware_v1.0.hex

Flashing workflow:

1. Device selection: Identifies the target CatSniffer.
2. Firmware resolution: Converts alias/partial name to complete file.
3. Integrity verification: Validates SHA256 before flashing.
4. Bootloader mode: Places the chip in programming mode.
5. Flash erasure: Clears existing flash memory.
6. Writing: Transfers the new firmware with a progress indicator.
7. Post-write verification: Confirms data was written correctly.
8. Identification: Sends a command to confirm visual identification of the device.
9. Reset: Returns device to normal operating mode.

---

Device verification

Catnip can run a verification test to confirm that the CatSniffer hardware is working correctly. Runs fundamental communication and detection tests.

Command:

catnip verify <OPTIONS> <COMMAND>

Argument <OPTIONS>	Description
--device, or -d INTEGER	Device ID (for multiple CatSniffers). If not specified, the first device will be selected

Argument <COMMAND>	Description
--help	Display the help menu and available <COMMAND>
--quiet, or -q	Supress detailed output
--test-all	Run a comprehensive set of tests including radio transmission/reception

When verification fails, the system provides detailed information to diagnose the problem.