SmartRF Sniffer Agent

SmartRF Sniffer Agent uses TI Hardware to capture over the air (OTA) data and then sends the packets to Wireshark or a PCAP file.

Sniffer Agent Data Input & Output Overview

Data Input

The following data input methods are supported:

• Socket - (Server Mode). Data is received from sent from one or more Sniffer Agent Client(s) from other machine(s).
• TI Sniffer Device(s) - TI Hardware with Sniffer firmware installed There are no Sniffer Agent limits on the number of hardware sniffers in use.

Data Output

The following data output methods are supported:

• Pipe - (Recommended) Data sent to Wireshark on local machine. (Windows 7 or higher only)
• Socket - (Stand Alone Mode) Data sent to the Microsoft Loopback Adapter with Wireshark running on your local machine.
• Socket - (Remote Mode) Data sent to Wireshark on another machine or your local machine using your network adapter.
• Socket - (Client Mode) Data is sent to the Sniffer Agent Server on another machine. You can still use Pipe and File to see or store data locally.
• Socket - (Server Mode) Data is received from sent from one or more Sniffer Agent Client(s) from other machine(s). The Server can also collect TI Sniffer data locally.
• File - Data is sent to a PCAP file(s) that can be opened in Wireshark.

Note: Pipe, Socket and File can all be selected at the same time.

How “Socket Config” Service Mode Affects Socket Usage

Service Mode	Incoming Socket	Outgoing Socket
Stand Alone	Not Used	Available for local use
Remote	Not Used	Used to send data to remote Wireshark
Client	Not Used	Used To send data to Sniffer Agent server
Server	Used	Available for local use

Note: File and Pipe are available for local use in all service modes.

Pipe - Window 10 & Windows 7 Quick Start

1. Install Sniffer Agent

2. Run Sniffer Agent

3. Under Data, Select -> Use Pipe.

4. Press the “Device Configuration” button, select a sniffer device and channel to use, then Press Done.

5. Press “Start All”, incoming data should go green and outgoing should turn blue. (Sniffer Agent icon will be blue)

6. Create a new Wireshark desktop shortcut, modify the “target:” by adding ” -i.pipesniffer_agent_data -k” to the end. (Do not copy the quote marks!)

   Example Target Entry:

   C:\<your path here>\wireshark.exe" -i\\.\pipe\sniffer_agent_data -k

7. Run Wireshark from the new shortcut which will open the other end of the pipe that Sniffer Agent has already has open.

8. Wireshark will show captured data and the Sniffer Agent will turn green.

PC Configurations

• Pipe: No PC configuration needed
• File: No PC configuration needed
• Socket: Configuration steps for Microsoft Loopback Adapter are described in the following sections.

Adapter Installation:

To use Sniffer Agent in Socket mode the user must install the “Microsoft Loopback Adapter”. Please follow the instructions exactly.

Follow the install procedures at “http://wiki.wireshark.org/CaptureSetup/Loopback”.

Win 7: http://msdn.microsoft.com/en-us/library/windows/hardware/ff553639(v=vs.85).aspx <or> http://blogs.msdn.com/b/ukvsts/archive/2009/02/27/adding-the-ms-loopback-adapter-on-windows-7.aspx

Adapter Configuration:

(Do not use the Device Manager to configure the loopback adapter.)

Win 7: Use Control Panel -> Network and Sharing Center -> Change Adapter Settings

1. Select the Microsoft Loopback Driver and hit the right mouse button and select properties.
2. Highlight Internet Protocol Version 4 (TCP/IPv4).
3. Press the Properties button.
4. Select the “Use the following IP address” radio button.
5. Set the IPV address to “192.168.1.2”.
6. Press the OK button.
7. If the properties show Internet Protocol Version 6 (TCP/IPv6) make sure to uncheck the option.
8. Sniffer Agent will setup the routing for you when you hit the start button. Reboot your computer. (This is mandatory!) Once again you will need to restart your computer to allow Wireshark to see the MS Loopback Adaptor and for the data to route properly.

Optional Settings for the Loopback Adapter

The NetBios Setting will broadcast some messages at start up. These messages can be suppressed. (Do not use the Device Manager to configure the loopback adapter.)

Win 7: Use Control Panel -> Network and Sharing Center -> Change Adapter Settings

1. Select the Microsoft Loopback Driver and hit the right mouse button and select properties.
2. Highlight Internet Protocol Version 4 (TCP/IPv4)
3. Press the Properties button.
4. Press the Advanced button.
5. Select the WINS tab.
6. Select the “Disable NetBIOS over TCP/IP” radio button, then press OK, OK and Close.

Firewall Configuration:

You may need to set your firewall to allow use of “192.168.1.2”; the procedure varies based on the firewall you have installed.

Sniffer Agent Operation

It is recommended that the program defaults be used whenever possible, with the exception of the channel number or frequency. The user may change a number of settings. Settings are stored when the user presses the start button and on program exit. The capture device selections are saved and the settings are retained as long as the device stays in the same port. Starting Sniffer Agent will show the following default settings:

Pipe Default Values:

• Pipe Name = sniffer_agent_data
• Layer Name = LINKTYPE_IPV4
• Layer Number = 228
• UDP IP Address = 192.168.1.3
• Port Number = 17760 (TI Radio Packet Info)
• Packet Limit = 0 (unlimited)

Socket Default Values:

• Service Mode = Stand Alone
• Destination IP Address = 192.168.1.3 (Unused IP Address)
• Destination Port Number = 17760 (TI Radio Packet Info)
• MAC Address = 00-00-00-00-00-00
• Target IP Address = 192.168.1.2 (MS Loopback Adaptor)
• Packet Limit = 0 (unlimited)

File Default Values:

• File Name = <none>
• Layer Name = LINKTYPE_IPV4
• Layer Number = 228
• UDP IP Address = 192.168.1.3
• Port Number = 17760 (TI Radio Packet Info)
• Packets Per File = 250000 (Enabled)
• Packet Limit = 100000000

This program supports TI LaunchPads with Packet Sniffer firmware programmed. The Sniffer Agent supports the use of multiple sniffer boards at the same time and all data is sent to the same IP address and port number.

Firmware

The LaunchPad board used as packet sniffer must have the latest version of the Packet Sniffer software programmed. The firmware is part of the SmartRF Packet Sniffer 2 installation.

Wireshark

Use the version of Wireshark that is recommended by the SmartRF Packet Sniffer 2 User Guide.

Running Sniffer Agent

1. Run Sniffer Agent
2. Select the data transfer method(s) to use.
3. Select the capture device(s) to use.
4. Change any parameters as needed. (Optional)
5. Click on start all.

Running Wireshark (Pipe)

The following steps are specific for the Pipe output method:

1. Sniffer Agent must be running in Pipe mode and Start has been pressed.

2. 1. Start Wireshark and enter the pipe name in the Capture Interface name You must use a full path name when specifying a pipe i.e. “.pipesniffer_agent_data” (Do not copy quote marks!)

   Or

   b. Start Wireshark with a modified shortcut that specifies the pipe. C:\<your path here>\wireshark.exe" -i\\.\pipe\sniffer_agent_data -k You must include the -i and -k options. This is the preferred way to use a pipe with Wireshark.

Pipe Tips

1. Always press start in Sniffer Agent first before starting Wireshark.
2. Leave Pipe Open, will leave the pipe open even if all devices are stopped.

Pipe Data Flow Examples

1. Sniffer Agent Not Running, Wireshark started using shortcut method, and reports pipe name error -> The Sniffer Agent must be running first.
2. Sniffer Agent Running, Wireshark started using shortcut method, and data is displayed -> this is normal operation.

Running Wireshark (Socket - Stand Alone mode to MS Loopback Driver)

1. Start Wireshark and select the “MS Loopback Driver” as the capture device.
2. OTA (Over the Air) packets will start to appear as they are received.

Running Wireshark (Socket - Remote mode) [Win 7/Win 10]

1. The socket destination address is the IP address of the remote machine and the service mode is Remote.
2. Sniffer Agent must be running in Socket mode and Start has been pressed.
3. Start Wireshark and select the network adapter on the remote machine. (If you have a problem, ensure that Sniffer Agent is sending to the remote machine’s IP address).

Socket Service Modes

1. Stand Alone (default). Packets are routed locally to Wireshark through the loopback adapter (one local machine, with 1 or more devices, sends to one Wireshark instance).
2. Remote. Packets are routed remotely to Wireshark (one remote machine, with 1 or more devices, sends to one Wireshark instance). This is a substitute since the server feature is off-line. A Wireshark filter is helpful since the machine receiving the packets will respond with a destination unreachable message. The following filter will remove those unwanted messages: !(ip.proto == 1) && udp.dstport==17760

Further information

1. You can stop an individual sniffer, change channels if desired and restart that sniffer, without affecting other devices.
2. You can select and start another sniffer after starting other sniffers.
3. Once one or more sniffers have been started, all sniffers must be stopped if you wish to add a new sniffer to your system.
4. Sniffers are discovered at start up and when the “Search for New Devices” is pressed.
5. The program configuration for devices is saved and will be restored. If a device is removed or moved to a new location the settings cannot be restored.
6. Installation of the Microsoft loopback adapter requires following the steps exactly, including reboots. If this fails to work, it is recommended that the loopback adapter be uninstalled and the process be started fresh after a reboot.
7. Wireshark is not provided with Sniffer Agent it is open source and can be downloaded from http://www.wireshark.org/.

Common Issues

1. If a “Communication Error” occurs when a device is started, try power cycling the sniffer hardware to correct the issue.
2. If a “Data Buffer Overflow” occurs, the Sniffer Agent program cannot get the data fast enough from the device. (Try any or all the following: Reduce CPU load, network traffic, and disk load from other programs, or reduce the number of devices that you are using to capture with.)

3. Wireshark reports memory corrupted or throws an assertion and exits. This is a Wireshark issue. The Sniffer Agent can deliver more messages in a short period of time than Wireshark can handle.

   • Try to reduce the number of sniffer devices option in use to reduce the flow to Wireshark or use the “File” data output method, or
   • Configure the Sniffer Agent packet limit option for the data output method you are using. When this limit is reached, Sniffer Agent will automatically stop the data capture that is running.

Further information

Command Line Options

The sniffer agent can be started from a command line and supports the following options:

• autostart - This option presses the “Start All” button and minimizes the Sniffer Agent application. If no devices start then a warning message will appear, and the application will stay minimized.
• resetcfg - This option forces the program settings to reset to program defaults.

Wireshark Time

The following sections describe how packet timestamps are handled in the different service modes.

Socket

In Socket mode the Sniffer Agent does not set the packet time displayed by Wireshark.

Pipe & File

1. When one device is selected, the time used is the sniffer time. (Resolution = microseconds)
2. When > 1 device is selected, the time used is the system UTC. (Resolution = 100 nanoseconds)
3. If one or more devices are selected and started while already running with one device, the time will be automatically changed to system UTC.
4. Once UTC time is set all devices must be stopped, before condition 1 above can be used.

Using the Wireshark default, the first packets received may have negative times if “one sniffer device” is used. Changing the Wireshark time format will start the packets from 0.

• (Wireshark Menu) View -> Time Display Format -> Seconds since 1970-01-01, or
• (Wireshark Menu) View -> Time Display Format -> Time of Day

Wireshark Capture Files (PCAP)

Sniffer Agent can send OTA data directly to Wireshark Capture Files (PCAP)).

Capturing data and sending directly to a file is I/O intensive and requires that the machine used for this operation is dedicated to Sniffer Agent while it is running during the capture process. Any other programs like disk defragmenters, compilers or data backups may cause one or more of the capture devices to automatically stop.

If you are not using file splitting, only one file is created.

It is very possible that the resulting PCAP file(s) could use up all available disk space. The size of the resulting PCAP file depends on the data received and the number of packets processed. It is recommended that doing a short timed test to determine the file size and packets captured. Setting the file packet limit can then automatically stop Sniffer Agent when the limit is reached.

Wireshark is not used during Sniffer Agent data processing. The resulting file can be opened in Wireshark after Sniffer Agent has come to a stop.

PCAP file(s) can quickly become very large and Wireshark will not be able to open the file created. Wireshark provides a tool called editcap that can be used to edit/split up the PCAP files. Please refer to the Wireshark documentation for more information on editcap.

Here is a command prompt example of how to split a large PCAP into multiple files that contain one million packets each.

editcap big.pcap split.pcap -C 1000000

The resulting split pcap files can be open individually to inspect the captured data.

The packet times in the split files will be relative to each file. To see the time as captured in the big pcap file use the following:

• (Wireshark Menu) View -> Time Display Format -> Seconds since 1970-01-01, or
• (Wireshark Menu) View -> Time Display Format -> Time of Day

Capture Filter

[Advanced Users Only]

This feature allows the user to filter messages and discard them before they are sent to Wireshark via Pipe, Socket or File.

Under the Options menu select the Capture Filter.

“Enable Capture Filtering” checkbox is used to turn this feature on and off. The message data provided for filtering has the time and data length bytes removed.

A filter fits inside an “if (condition)” statement. The filter is “only” the condition part of the statement inside the parenthesis. The condition must resolve to a Boolean value. If condition is true the data is discarded and if false or there is an error exception the data is sent to Wireshark. You are allowed to do whatever is allowed by the C# compiler within that condition area. Your filter must build without errors or warnings. Only one filter is enabled at a time, the filter used is the one displayed on the Capture Filter form.

It is important to note that a filter is a time critical function, especially when multiple sniffers are in use. All filter examples were tested with multiple dongles with no performance issues. Filter exceptions (errors) can be reduced by checking data length before looking at a data byte that is not there. If an exception occurs when running the filter, the message is sent through possibly reducing the effectiveness of your filter. All incoming data to the user filter will have at least one data byte.

The filter has access to an array of bytes and two integer local variables. Pointers and pointer operations are not allowed in a user filter. Message data is “byte[] data”, which is a “System.Array” class that contains the message data. Note that the length of data is done by accessing the class property “Length” is “data.Length”. Optional local variables are “int x = 0” & “int y = 0”, a primitive data type.

Some of the logical operators allowed: Logical operators -> && (And), || (Or), ! (Not) Bit-wise Logical Operators -> & (And), | (Or), ^ (Xor)

Note: Bit-Wise Operator Format ((data[0] & 0x02) == 0x02) // suppress ack frame type The bit wise operator result is not a Boolean value, thus the need for the double equals.

Here is the filter function

//--------------------------------------------------------------------------------
//  @fn       Apply()
//  @brief    Apply a filter to the data
//  @param    byte[] data - the data to check
//  @returns  bool - true = discard and false = do not discard or exception
//--------------------------------------------------------------------------------
public bool Apply(byte[] data)
{
  bool returnCode = false;

  try
  {
    #pragma warning disable 219
    // user filter local variables
    int x = 0;
    int y = 0;
    #pragma warning restore 219

    // check the filter result
    if ( user filter added here )
    {
      returnCode = true;
    }
  }
  catch
  {
    // anything unexpected happens data is not discarded
    returnCode = false;
  }

  return returnCode;
}

Below are some example filters to get you started.(You can copy and paste these individual filters into new filters.)

A filter fits inside an if (condition) statement. The filter is only the condition part of the statement inside the parenthesis.

• bool condition:

  • true = discard data
  • false = send data or a condition error

• Message data -> byte[] data, a System.Array class containing the msg data

• Local variables -> int x = 0 & int y = 0, a primitive data type

• Boolean operators:

  • && (And)
  • || (Or)
  • ! (Not)

• Bit-wise Logical Operators:

  • & (And)

  • (Or)

  • ^ (Xor)

Examples:

1. Discard all:

true

2. Allow One Pan Id:

((data.Length > 5) &&
 !((data[3] == 0x11) && // allow pan id 0x0611
   (data[4] == 0x06)))

3. Suppress Ack Frame Type:

((data[0] & 0x7) == 0x02)  // suppress ack frame type (frame type field is bit 0-2)

4. Suppress Unknown Frame Type:

((data[0] & 0x7) >= 0x04)  // suppress unknown frame type

More info about C# syntax:

1. C# if-else Reference: http://msdn.microsoft.com/en-us/library/5011f09h(v=vs.110).aspx
2. C# Boolean Logic: http://msdn.microsoft.com/en-us/library/hh147286(VS.88).aspx#Boolean
3. Google Search: Use “c# msdn <your question>”

References

1. Wireshark -> http://www.wireshark.org/
2. TI E2E -> http://e2e.ti.com/support/low_power_rf/f/159.aspx