Packet Sniffer

A CC1350 or CC1310 Launchpad board can be used as packet sniffer device for TI 15.4-Stack radio packets. This feature enables easier development and debugging for those developing products with the TI 15.4-Stack. This section provides details on the required software, where to get it, and how to set it up to sniff the over-the- air (OTA) traffic. Wireshark™ is the recommended packet sniffer.

The CC13x0 SimpleLink SDK installs the essential software tools required to set up the packet sniffer. The TI 15.4-Stack installs the TiWsPc2, which uses TI hardware to capture OTA data before sending the packets to Wireshark or a PCAP file, and provides .dll files to dissect packets that follow the TI 802.15.4ge protocol to Wireshark. Figure 62. is an example of TI 15.4-Stack-based application OTA traffic being presented as a Wireshark capture.

../_images/fig-wireshark-ota-traffic.png

Figure 62. OTA Traffic

Choose a packet to get detailed information on the data in that packet. The installed .dll file lets Wireshark dissect the information in a TI 802.15.4GE packet for easy debugging.

Setting Up the Sniffer

Install the Required Software

  1. Install the CC13x0 SimpleLink SDK. This SDK installs:

    • TiWsPc2 at

      C:\ti\simplelink_cc13x0_sdk_1_40_00_xx\tools\ti154stack\TiWsPc2

    • .DLL files at

      C:\ti\simplelink_cc13x0_sdk_1_40_00_xx\tools\ti154stack\tiwsds\plugins

  2. Install the 2.2.x stable Wireshark release from https://www.wireshark.org/#download. The architecture version downloaded (64-bit vs 32-bit) effects which plug-in to install.

    Note

    Use only version v2.2.x. Other Wireshark versions may not be compatible.

  3. Run the Wireshark installer as administrator. If this step is not done and a previous Wireshark version is installed, the installer can fail with the message: Error opening the file for writing: C:\ProgramFiles\Wireshark\uninstall.exe

  4. Download SmartRF Flash Programmer 2 from https://www.ti.com/tool/flash-programmer and install it. This tool is used to program firmware for the packet sniffer device.

Hardware Setup

Required Hardware

Either of the following boards can be used as packet sniffer device:

  • CC1350 Launchpad with chip revision 2.1 or later (LAUNCHXL-CC1350).
  • CC1310 Launchpad with chip revision 2.1 or later (LAUNCHXL-CC1310).

Setup

The Launchpad board must be programmed with the correct firmware before it can be used as packet sniffer. The firmware image to use depends on the frequency band and TI-Stack PHY mode. See Table 1‑1 below.

Table 18. Firmware Hex Files for 15.4 Stack
Frequency Band PHY Firmware Hex File
868 and 915 MHz bands GFSK 50 Kbps sniffer_fw_gfsk_50kbps_868_915.hex
433 MHz band GFSK 50 Kbps sniffer_fw_gfsk_50kbps_433.hex
868 and 915 MHz bands GFSK 50 Kbps Legacy sniffer_fw_gfsk_50kbps_868_915_legacy.hex
868 and 915 MHz bands SLR (SimpleLink Long Range) 5 Kbps sniffer_fw_slr_5kbps_868_915.hex
433 MHz band SLR (SimpleLink Long Range) 5 Kbps sniffer_fw_slr_5kbps_433.hex

The firmware can be programmed with SmartRF Flash Programmer 2.

Perform the following steps to program the Launchpad board with sniffer firmware:

  1. Connect the Launchpad board to the PC with a USB cable.

  2. Start SmartRF Flash Programmer 2. See Figure 63. below.

  3. Select the CC1350/CC1310 device in the list of connected devices at left side.

  4. In the Main tab browse to the correct sniffer firmware image depending on your TI 15.4-Stack configuration (See Table 18.). The sniffer firmware images for 15.4 Stack are located with the SimpleLink CC13x0 SDK installation in the folder

    C:\ti\simplelink_cc13x0_sdk_1_40_00_xx\tools\ti154stack\TiWsPc2\sniffer_fw\bin\15.4g

  5. Make sure that Erase, Program and Verify are checked. Then click the ‘Play’ button at the lower right side in the Main tab to initiate the programming.

    ../_images/fig-sniffer-flash-programmer2.png

    Figure 63. SmartRF Flash Programmer 2

For more information about the sniffer firmware, please see the documentation found in the sniffer_fw/docs folder located with the TiWsPc2 installation.

Software Setup

Texas Instruments Wireshark Packet Converter 2 Setup

The following are ways to transfer data from Texas Instruments Wireshark Packet Converter 2 (TiWsPc2) to Wireshark:

  • Pipe – (recommended): data is sent to Wireshark on the local machine. (Vista/Windows 7 or higher only)
  • Socket – (stand-alone mode): data is sent to the Microsoft Loopback Adapter with Wireshark running on the local machine.
  • Socket – (remote mode): data is sent to Wireshark on another machine or the local machine using the network adapter.
  • File – data is sent to a PCAP file that can be opened in Wireshark.

The following guide demonstrates how to use the pipe solution with Windows 7. More advanced users might want to try a socket. For more details, consult the TiWsPc2 README for instructions.

  1. Run TiWsPc2.

  2. Select Data → Data Out, check Use Pipe, and click Ok as shown in Figure 64..

    ../_images/fig-sniffer-output-mode.png

    Figure 64. Use Pipe

  3. Press the Device Configuration button. Select a sniffer device, frequency band and channel to use, then press Done. (Make sure that the sniffer firmware that matches the selected frequency band is programmed on the sniffer device. See Table 18.).

  4. Press Start All; incoming data goes green, and outgoing turns blue. The TiWsPc2 icon is blue.

  5. Create a new Wireshark desktop shortcut, modifying the target by adding -i\\.\pipe\tiwspc_data -k to the end, as shown in Figure 65..

    Example target entry: C:\<path>\wireshark.exe" -i\\.pipe\tiwspc_data –k

    ../_images/fig-wireshark-target-options.png

    Figure 65. Shortcut Properties

  6. Run Wireshark from the new shortcut, which opens the other end of the pipe.

    Wireshark now shows captured data and the TiWsPc2 turns green. Packets sent to UDP address 17760 indicate TI RPI (Radio Packet Info) packets. Now set up the dissectors to enable detailed dissection of TI RPI and IEEE 802.15.4g protocol.

Wireshark Dissector Setup

  1. Check which architecture version (32-bit or 64-bit) of Wireshark was downloaded. Follow Step 2 according to that choice before going to Step 3.

  2. For 32-bit: Copy ti802154ge-x86-2x.dll and tirpi-x86-2x.dll

    From:

    C:\ti\simplelink_cc13x0_sdk_1_40_00_xx\tools\ti154stack\tiwsds\plugins
    To:

    C:\Program Files (x86)\Wireshark\plugins\2.2.x (x can be any number)

    For 64-bit: Copy ti802154ge-x64-2x.dll and tirpi-x64-2x.dll

    From:

    C:\ti\simplelink_cc13x0_sdk_1_40_00_xx\tools\ti154stack\tiwsds\plugins
    To:

    C:\Program Files\Wireshark\plugins\2.2.x (x can be any number)

  3. Open Wireshark, and check that the plugins are installed by going to Help->About Wireshark and clicking the Plugins tab. The ti802154ge-x (32/64)-2x.dll file and tirpi-x(32/64)-2x.dll are both listed, as shown in Figure 66..

    If so, the plugins are installed and receives packets from TiWsPc2. If not, see the following for troubleshooting.

    ../_images/fig-wireshark-plugins.png

    Figure 66. Wireshark Plugin

  4. Navigate to Edit → Preferences and select Protocols → TI 802.15.4GE under the left- hand menu. If you use secured packets, add a decryption key and static address pairings (for pairing short address and PAN-IDs with long addresses for decryption).

    ../_images/fig-wireshark-preferences.png

    Figure 67. Wireshark Preferences

Using Wireshark

  1. To filter a certain packet attribute, right-click on the selected packet attribute.

  2. Choose Apply as Filter, and then Selected, as shown in Figure 68..

    ../_images/fig-wireshark-filter.png

    Figure 68. Apply Filter

  3. In the filter textbox, select a filter of the form ti802.15.4ge.<attribute>==0x<XXXX>. Figure 69. shows how to filter the capture to display only TI 802.15.4GE data packets.

    ../_images/fig-wireshark-filter-delection.png

    Figure 69. Filter Selection

  4. Get the attribute name of any field in a packet, as well as a description based on the specification, by looking to the bottom of the screen, underneath the raw packet data viewer, as shown in Figure 70..

    ../_images/fig-wireshark-attribute-name.png

    Figure 70. Get Attribute Name

Troubleshooting

TiWsPc2 Troubleshooting

  • If a Communication error occurs when a device is started, try power-cycling the sniffer hardware to correct the issue.
  • If a Data Buffer Overflow occurs, the TiWsPc2 program cannot get the data fast enough from the device. Try any or all of the following: reduce CPU load, network traffic, and disk load from other programs, or reduce the number of capturing devices.
  • If Wireshark reports corrupted memory or throws an assertion and exits, this is a Wireshark issue; TiWsPc2 can deliver more messages in a short period of time than Wireshark can handle. Try reducing the number of sniffer device options in use, to reduce the flow to Wireshark using the file data out. Alternatively, configure the TiWsPc2 packet limit option for the selected data output method. When this limit is reached, TiWsPc2 automatically stops the current data capture.

Wireshark Dissector Troubleshooting

  • If after installing Wireshark, the error shown in Figure 71. appears, a 64-bit plugin is installed, but you are using 32-bit Wireshark. To debug, repeat Steps 1 and 2 Wireshark Dissector Setup.

    ../_images/fig-wireshark-plugin-error.png

    Figure 71. Wireshark Plugin Error

  • If after starting Wireshark, the error shown in Figure 72. appears, delete one of the two TI 802.15.4ge plug-ins in the Wireshark plug-ins folder

    ../_images/fig-wireshark-console-error.png

    Figure 72. Wireshark Debug Error

  • When opening Wireshark, you may get an error that opens a command prompt from the Wireshark Debug Console and reads Err Field (abbrev=’Frame Length’) does not have a name, and Press any key to exit. Alternatively, you may get a message that reads The procedure entry point ep_alloc could not be located in the dynamic link library libwireshark.dll. These start-up errors indicate that the installed plug-in is for an incompatible version of Wireshark. Check this by going to Help → About Wireshark, and check that the version number is 2.2.x. If the version number is not 2.2.x., download and install a 2.2.x release, because the plug-in is not backwards-compatible.

  • For any other questions or problems, consult the README at

    C:\ti\simplelink_cc13x0_sdk_1_40_00_xx\tools\ti154stack\tiwsds\README.rtf