USBee DX PacketPresenter™

Included with the USBee DX, the PacketPresenter™ displays the bus traffic that is being transmitted between ICs or system components in a graphical, easy to understand packet format that can be customized to your specific design.

With standard logic analyzers, engineers have been accustomed to counting bits, manually decoding protocols, and parsing embedded bus traffic into useable fields. The PacketPresenter does this for you automatically. With the PacketPresenter, counting bits on a logic analyzer is a thing of the past.

The PacketPresenter translates standard logic analyzer traces into graphical communication packets that are easy to read and understand. The PacketPresenter saves you time by automatically extracting the protocol information of interest from raw bus traffic and presenting it in a clear and simple format. You no longer need to count bits or decode waveform traces to find out what your system is saying.

Many existing Protocol Decoders understand only a single protocol. The PacketPresenter, on the other hand, is customizable to fit your custom and unique embedded bus protocol using a simple and intuitive configurable PacketPresenter Definition file. And unique to the USBee DX, the PacketPresenter gives you a detailed look into how the packet communications on your embedded bus relates to the actual voltage-versus-time waveforms of the bus signals.

Debugging is performed by viewing and analyzing the PacketPresenter output and relating it back to the logic analyzer waveforms and decoded bus traffic for the various types of busses. For example, you can see the PacketPresenter display of HDLC communication packets, and correlate that back to the raw byte stream that was decoded from the ASYNC bus, as well as the voltage versus time waveforms of the bus Tx and Rx lines.

The PacketPresenter feature runs alongside the existing bus decoders. It takes the output of raw binary data from the bus decoder and parses the stream according to a PacketPresenter Definition File for the intent of displaying the communications in easily understood graphical displays.

Protocols are defined using a text file, called a PacketPresenter Definition File, which specifies the fields within the protocol and how to display that information on the screen. It is generic enough that you can create your own protocol decoders for your own custom bus types.

Each PacketPresenter Definition File correspond to one single bus type, and the incoming bytes from that bus are inputs for the decoding process. This steam of data is called an incoming Data Stream and it is handled by a Protocol Processor. Each Protocol Processor takes a single incoming Data Stream that is broken into Packets, parsed into Fields and either displayed as a field on the screen, ignored, and/or sent to a new Protocol for further processing (as in an N layer protocol).

Each Protocol Processor defines how to break the stream into Packets, and how to break the Packets into Fields. These Fields can then be displayed or sent to another Data Stream for further processing.

Each digital waveform on the screen can be defined as a different bus (I2C, SPI, etc.) in the Channel settings dialog box by clicking on the white box to the left of the signal name. Below shows the Channel Settings dialog box.

To enable the PacketPresenter for this channel, check the “Display the Data Stream using the following PacketPresenter definition file” checkbox. Then choose the PacketPresenter definition file by clicking the button to the right. Once you choose the file, you can edit the contents by clicking the “Edit File” button.

Once the PacketPresenter is enabled all bus decodes will be processed through the PacketPresenter as well as the original bus decoder.

Once the bus is defined and the PacketPresenter is setup with a PacketPresenter definition file, right clicking and dragging on the waveform will not only decode the raw data from the bus (as specified in the Channel Settings), but will also parse the data based on your PacketPresenter definition file.

If the PacketPresenter is not enabled, only the decoded data is shown as seen below.

Enabling the PacketPresenter shows the PacketPresenter output, with the original decoded data in a minimized window as in the following screenshot.

You can show the raw decoded data at the same time by restoring the minimized window as shown in the following screenshot.

You can copy the contents of the PacketPresenter output window to other programs in a number of ways.

First, you can copy the screenshot of the window by selecting the window and pressing Alt-PrtScr on your keyboard. This copies the image of the window to the Windows clipboard and you can paste that image into any program that accepts images.

You can also use the Edit | Copy menu item. If the textual decode data window is active, the selected text is copied to the clipboard. To select text, just click and drag across the text you would like to highlight. If the PacketPresenter output window is highlighted, all packets starting with the packet at the top of the window are copied to the clipboard. When pasting the data to other programs, it will paste the data as an RTF file if possible and text otherwise.

You can also save the PacketPresenter output to either a Text file or an RTF file (Rich Text Format). The text file output is a textual representation of the packets as seen below.

Saving data to an RTF file format saves the graphical nature of the packets and can be read by many word processing programs, such as Microsoft Word and WordPad. Below is a screenshot of data saved to an RFT file and viewed using WordPad.

You can change the size of the fonts used by the PacketPresenter by selecting the View | Larger or View | Smaller menu items. Below are examples of different size fonts.

Once displayed, you can search for the next packet that contains certain fields that match your criteria. Below is the Search Packet dialog box that is shown by using the View | Packet Search menu item.

In the leftmost textboxes, type the Field Label. Then select the comparator operator (equals, not equals, less than, greater than…) and finally the value that the field is to be compared against. Finally, if there is more than one field in the search list, choose whether to AND or OR the search terms. When you click Find, the next packet in the list (starting from the top of the window) will be placed at the top of the window. You can search forward or backward by selecting the appropriate radio button on the right.

Once displayed, you can filter the output to only show packets that contain certain fields that match your criteria. Below is the Filter Packet dialog box that is shown by selecting the View | Packet Filter along with the resulting PacketPresenter output.

In the leftmost textboxes, type the Field Label. Then select the comparator operator (equals, not equals, less than, greater than…) and finally the value that the field is to be compared against. Finally, if there is more than one field in the search list, choose whether to AND or OR the search terms. When you click Filter On, only the packets matching the criteria are displayed. To turn off the filtering, click on the Filter Off button.

Using the Window | Tile menu you can choose to show the open windows Horizontally, Vertically or Cascaded as displayed below.

When you click on a packet in the PacketPresenter output window, the entire packet is highlighted and the associated raw decoded data is highlighted in the decode window. The original waveform screen is also shifted to center the start of the packet in the logic analyzer window.

This feature allows you to correlate what is shown in the PacketPresenter window to the actual waveform on the logic analyzer that created that packet.

You can place the cursors using the PacketPresenter window by using the left and right mouse buttons. Place the mouse over the packet you want to place the cursor on and click the left or right button. The cursors are placed at the beginning of the packets. The resulting difference between cursors s shown at the bottom of the screen.

If more than one bus is being shown, you can measure the time between packets on different busses using the cursors as shown in the following screen. Set the first cursor by left clicking in the first window and place the second by right clicking in the second window.

Each PacketPresenter Definition file defines how the incoming data stream is represented in the PacketPresenter screen of the USBee DX MSO application. These PacketPresenter Definition files are in text format and are easily created using a simple text editor.

Each bus defined in the USBee DX MSO application can have a different PacketPresenter Definition File.

The intent of the PacketPresenter is to produce a series of 2 dimensional arrays of labels and values to be displayed as below by the user interface.

It is the PacketPresenter Definition File that defines how the data is to be parsed and displayed.

Constants are fixed numbers anywhere in the file. These constants can be expressed as decimal, hex, or binary using suffixes after the value. Decimal has no suffix. Hex uses the suffix “h”. Binary uses the suffix “b”.

Gain and offset values used in the Fields section are always in decimal and can contain decimal places.

Each PacketPresenter Definition File has the following syntax that separates the file into sections that correspond to the Channel definition and each of the Protocol Processors.

Each Protocol Section defines what the incoming data stream looks like, how to break the data stream into packets, and how to parse out the fields in each of the packets. Multiple Protocol Sections can be defined for passing data from one Protocol Section to another.

Each Protocol Section has the following syntax that specifies the packetizing and parsing into fields.

[Protocol]
name = ProtocolName
[Packet]
   packet processing settings
[Fields]
   packet field processing settings
   packet field processing settings
   packet field processing settings
   . . .

The ProtocolName is a label that uniquely identifies this protocol processor. This name is used in the Field definitions to define which Protocol to route a field of data (for use by multilayer protocols).

The highest level Protocol is the first protocol in the file. This is the Protocol Processor that is sent the incoming data stream from the bus as defined in the Channel Settings Dialog Box for that waveform.

Some busses are by nature byte oriented, while others are bit oriented. The following table shows the type of bus.

Each bus type also can have certain bus events that may be significant in the decoding of a protocol. One such event is an I2C Start Bit. While the Start bit is not an actual bit in the data stream, it does signify to the I2C slave that a certain transaction is taking place. These bus events are inserted into the data stream and can be used (or ignored) by the protocol processors. The list of Bus Events supported is in the following table.

Bus Type	Event
Async	1 – Parity Error
I2C	1 - Start Bit 2 - Stop Bit 4 - ACK 8 – NACK
SPI	1 - SS Active 2 - SS Inactive Note: You MUST have SS On in the channels settings for these events to occur
USB	1 – SETUP/IN/OUT Received 2 –ACK/NACK/Stall Received 4 – No Handshake received
CAN	1 – Start of CAN packet 2 – End Of CAN packet
1-Wire	1 - Reset Found 2 - Presence Found
Parallel
Serial
PS/2	1 – Device to Host byte follows 2 – Host to device byte follows
I2S	1 - WordSelect Active 2 - WordSelect InActive
SMBus	1 - Start Bit 2 - Stop Bit

A Bus Event of 127 (7Fh) is a special event that occurs at the end of a packet of data that is sent from one protocol to another. This can be used to end the packet sent to the new layer using the [END] section and the type = event in the new protocol level.

Some buses can also have more than one data signal used in the protocol. One example of this is the SPI bus, where for each byte sent on the MOSI line there is one byte received on the MISO line. In the protocol definition you can specify which of the signals to expect the next field of data to be sent on. In the SPI example, you may get a Command and Length field on one signal, followed by the read data back on the other signal. The decoder would take that into account and show the command, Length and Data as a single transaction.

Multiple signals are differentiated in the PacketPresenter using the X and Y channel specifiers. These channels are specified by selecting the signals to use for that bus in the Channel Settings dialog box. The following table shows which signals are the X and Y signals.

Packet Section

The Packet section defines how a packet is bounded and what, if any, preprocessing needs to be done on the packet before the fields can be processed.

Start and End Sections

The Start and End sections define how a packet is bounded. The available packet bounding Types are defined below:

Next: The next byte or bit is assumed the start of a packet
Signal: An external signal indicates the start of a packet
Value: A specific value in the data indicates the start of a packet
Event: A bus specific bus Event or Events indicates the start of a packet

Next: The next byte or bit is assumed the end of a packet
Signal: An external signal indicates the end of a packet
Value: A specific value in the data indicates the end of a packet
Length: A specific or calculated length determines the end of a packet
Event: A bus specific bus Event or Events indicates the end of a packet
Timeout: A packet ends after a set timeout without data or events

type = Next

[Packet]
[Start] or [End]
type = Next ; Start/End of a packet is the
; next byte/bit to arrive

type = Signal

The start or end of a packet can be indicated by a separate signal (such as a chip select or a frame signal) using the signal setting.

[Packet]
[Start] or [End]
type = signal              ; Start/End of a packet is based
                                 ; on a signal
signal = signalvalue      ; Signal number 0 - 15
level = 1          ; level the signal needs to be

type = Value

The start or end of a packet can be indicated by a certain data value contained in the data using the value setting. Multiple values can be used, where any one match starts or ends a packet. All bits in the Value are included in the resulting packet at the start of the packet. You must also specify the number of bits that the value covers (defaults to 8 bits if not specified) using the bits keyword. You can specify a mask value to apply to the start data and values. When the mask value has a bit that is a 1, that bit in the value and data are compared.

[Packet]
[Start] or [End]
type = value ; Start/End of a packet is based on a data value
mask = bitmask      ; Bitmask to apply to the data stream
value = value1      ; value that the data needs to be to start/End
value = value2      ; value that the data needs to be to start/End
value = value3      ; value that the data needs to be to start/End
bits = 8      ; how many bits in the start/End word

type = Length

Only valid in the [END] section, the end of a packet can be indicated by a certain length of data. You use the BitLength or the ByteLength keywords to specify how long the packet is. The length can either be a fixed length expressed as a constant, or variable length based on the contents of a packet in the data stream.

type = length ; End of a packet is based on a length
Bytelength = length ; How many bytes per packet

To use the contents of one of the fields as the packet length, you use the name of the field defined in the Fields section. You can also do simple arithmetic on the field value to compute the final packet size.

type = length      ; End of a packet is based on a length
Bytelength = fieldname * 2 2
            ; field holding packet size
            ; * (or /) a constant (optional)
            ; (or -) a constant (optional)

For example, if fieldname Field has the contents of 16, then the following is true:

The length of the packet includes ALL of the data from each of the data channels for that bus. If the bus contains only one data channel (such as I2C), the length counts all data on that one bus. If the bus has two data channels, the length refers to all data on both channels combined.

type = Event

The start or end of a packet can be indicated by the reception of any of the bus specific Events. For example in I2C you get a Bus Event for each Start Bit and a Bus Event for each Stop Bit. In USB you get a Bus Event for each Sync word and a Bus Event for each EOP. Available bus types are defined in Table 1. Bus Event Types.

The event value is a bitmask that includes all events that you want to use. If any of the events occur, a packet will be started or ended.

type = Event ; Start/End of a packet is signaled by event
event = 1 ; Use Event 1. Available events depend on bus type

type = Timeout

The end of a packet is determined by a timeout since the last valid data or event on the bus. The timeout is defined in units of microseconds.

[Packet]
[Start]
type = timeout ; End is after timeout
timeout = 45 ; microseconds since last data/event received

CHANNELX, CHANNELY or CHANNELXorY

CHANNELX, CHANNELY or CHANNELXorY specifies what channel is used when an event or data is defined for starting or ending a packet. Channel X and Channel Y are different based on what the physical bus is and can be found in Table 2. Channel X and Channel Y Definitions Per Bus Type. If it does not matter which channel the data or event occurs on (it could be either), use the CHANNELXorY keyword.

[Packet]
[Start]
type = value ; Start of a packet is based on a data value
value = 41h ; value of data that starts the packet
bits = 8
channelX ; data/event must be received on channel X

Decode Section

Each packet can have encoding on the data that needs to be removed in order to see the real data. This section defines what decoding should be done to the packet. The entire packet from start to end is sent through the decoders. If only select parts of the packet needs to be decoded, you must create your own Add-In decoder using the ADDIN keyword.

Substitutions

Substitutions allow a sequence of bytes (up to 3) to be replaced with a different set (same size or less) of bytes. They can only be used on bytestreams, not bitstreams. Substrings define the bytes input and the bytes output. The Substrings must not contain any spaces. Examples of this are below:

[1][2]=[3][4] ; Replaces all 1 immediately followed by 2 with 3 immediately followed by 4

[1]=[2][3][4] ; INVALID, the number of output bytes must be less than or equal to the input

As an example, the HDLC protocol uses the byte value 7Eh as the start and end flag of the packets and replaces all 7Eh in the data with the bytes 7Dh followed by 5Eh. It also replaces all 7Dh in the data with the bytes 7Dh followed by 5Dh. To remove this coding you would use the lines:

Fields Section

Once the packet is delineated and decoded by the previous sections, it is ready to be displayed by the PacketPresenter. Since each packet is made up of fields, the Fields section defines how the packet is broken up into its fields and what to do with the field data.

Field Lines Processing

During processing, the Fields Section is processed one Field Line at a time in the order that they are listed in the FIELDS section. Each Field Line is parsed against the incoming data packets.

Once a single Field Line is successfully processed and output, the PacketPresenter starts over at the top of the Filed Lines list for the next packet. This ensures that there is only one output packet for each input packet for a given protocol.

There are 2 types of Field Lines. A Field Line can be conditional or unconditional. Unconditional Field Lines are processed for any packet. Conditional Field Lines are only processed if certain fields match a specific value.

Any Unconditional Field Line (no conditionals) generates an output line on the PacketPresenter screen. Any Conditional Field Line that evaluates to True generates an output line on the PacketPresenter screen. Any Conditional Field Line that evaluates to False is skipped and produces no output line on the PacketPresenter screen.

The Field Lines should be listed with the conditional field lines first followed by an unconditional field line to catch all packets that are not explicitly defined in the conditional field lines.

Unconditional Field Lines

Unconditional Field lines are parsed and decoded data is output for every packet that is input. The Fields specify how to interpret the data and how to output the data.

Conditional Field Lines

Conditional Field Lines provide a means for defining packets whose contents vary based upon the presence of a value in another field. An example of this is a packet that contains a Command Byte that determines the format of the rest of the packet. A Conditional Field Line contains at least one field in the packet that includes the =Value token in the input modifiers section.

If the data contained in the conditional fields of a packet matches the =Value specified for the field, the packet is parsed and the data is output. If the condition field =Value does not match the incoming data, then the processor moves on to the next Field Line until it reaches the end of the Fields section.

Field Line Format

Each Field Line in the Fields Section has the keyword FIELDS followed by a series of individual Fields. Individual fields in a packet are separated by commas. A Field line in the Fields Section defines an entire packet from start to end and has the form:

You can also insert a string to be printed out at that location in the packet by using the string ($) operator before the string to be printed. Below is an example of a field line with one string added between the fields.

Each field will be output with a Label and a Value. For String fields, the Label is blank and the Value is the String.

Field Format

Each field in the Field Line is defined using the following syntax and contains no spaces:

USBee DX PacketPresenter™

Overview

Setting Up the PacketPresenter

Viewing the PacketPresenter Output

Searching For Packets

Filtering Packets

Multiple Decode Display

PacketPresenter to Waveform Association

Cursors on the PacketPresenter Output

PacketPresenter Definition File Format

Comments in the PacketPresenter Definition File

Constants in the PacketPresenter Definition File

PacketPresenter Definition File Sections

Protocol Section

Byte-wise busses vs. Bit-wise busses

Bus Events

Data Channels and Multiple Data Signals