Home
This wiki page is meant to be a mirror copy of the content provided in the release's quick start guide.
The ABCC SPI Protocol Analyzer Plugin consists of the following features:
- Multi-layered framing of ABCC SPI fields
- 3-wire or 4-wire SPI support
- Indexed and searchable results (with analyzer filter options) for:
- Network timestamp (with packet counter)
- Anybus Status change events
- Application Status change events
- Error events (logical or protocol-wise)
- Error response messages
- Application error status events
- Anybus error status events
- SPI CPOL/CPHA/SS settings mismatch
- CRC32 error events
- Retransmissions (partial support)
- Buffer full (warning event)
- New messages (response, command, error response) with support for indication of SPI fragmentation protocol.
- Analyzer export options (uses CSV format with ’,’ delimiter by default)
- Export of:
- All frame data
- All message data
- All process data
- Export of:
- Saleae Logic (software) version 1.2.17
- Other versions will work so long as it is compatible with Logic SDK version 1.1.32.
- Saleae Logic analyzer (hardware)
- Operating system
- Microsoft Windows 7 or newer
- Apple OS X 10.7 Lion+ (or macOS)
- Ubuntu 12.04.2+
- Precompiled ABCC SPI Analyzer plugin
To install this plugin, it is assumed that the user has previously installed the Saleae Logic software using the default installation options. It is also assumed the default installation path is used (where applicable). Copy the corrsponding plugin source to the indicated destination path for the operating system being used as indicated in the table below.
| OS | Plugin source | Destination Path |
|---|---|---|
| Windows 64-bit | .\plugins\Win64\AbccSpiAnalyzer64.dll |
C:\Program Files\Saleae LLC\Analyzers\ |
| Windows 32-bit | .\plugins\Win32\AbccSpiAnalyzer.dll |
C:\Program Files\Saleae LLC\Analyzers\ |
| Linux 64-bit (Ubuntu) | .\plugins\Linux64\AbccSpiAnalyzer64.so |
.\Analyzers folder of the Logic software installation path |
| Linux 32-bit (Ubuntu) | .\plugins\Linux32\AbccSpiAnalyzer.so |
.\Analyzers folder of the Logic software installation path |
| macOS (OSX) | .\plugins\OSX\AbccSpiAnalyzer64.dylib |
.\Analyzers folder of the Logic software installation path |
If properly installed, the analyzer will appear in the “Analyzers” sub-window’s “add” option (+) as shown in the figure below.
After the analyzer has been selected, the settings window will be displayed as shown in the figure below. The default indexing options provide the most basic and, perhaps, most commonly used options, but can be changed according to your needs.
Select the corresponding channels that are associated with the physical MOSI, MISO, Clock (SCLK), and Enable (CS/SS) lines to the ABCC. The enable channel is optional and will function in 3-wire mode if set to ‘None’.
IMPORTANT NOTE: When using the plugin in “3-wire” mode there are minimum “idle gap” and maximum “clock idle high” timing requirements (>10us and <5us respectively). Also, the ABCC’s 3-wire SPI mode only supports “clock idle high” configuration and is enforced in the analyzer logic in such a configuration. See discussion on “Advanced Settings” for details on how to analyze 4-wire without monitoring the enable signal.
Each of the bubble-text frames (a term used by the Saleae Logic SDK that refers to the blue bars seen in the software) correspond to fields within an ABCC SPI packet. When applicable, these fields are processed and converted into human readable enumerations of the flags and values that make up the underlying ABCC communication. For instance, the bubble text frame shown in the figure below shows “ANB_STS: (PROCESS_ACTIVE | SUP)”. This indicates that the ABCC is in the process active state and is being supervised.
The figure below illustrates the multi-layered bubble text that the plugin supports. This example shows how the SPI Control field looks when zoomed out, and how it may look when sufficiently zoomed-in, revealing more verbose information about the state of the field. Additionally, when sufficiently zoomed-in, the logic signal will be drawn with ‘0’ and ‘1’ indicators over the exact sample point in the corresponding channel which reflect the state of the signal during that sample period.
To determine if the last, most detailed, bubble-text is currently being displayed the user can make the following observations:
- All frames will contain a single-character bubble-text entry
- This character will either be the first character of the “tag” or an “alert” represented by ‘!’.
- The currently used tag names are defined in the following section.
- All frames will contain a “tag” bubble-text entry
- This entry is meant to be short but readable enough for the user to determine its meaning when sufficiently familiar with the ABCC SPI telegram fields.
- In the case of an “alert”, the tag will be prefixed by “!ALERT -“.
- All frames will contain a “value”
- This value will use an appropriate “display radix” option for a given field. Fields that are naturally numeric values will not be permitted to display as a ”character” value and will restrict to using hex-format when the user sets the ”display radix” option as ASCII from the Logic software.
- Optionally, frames may contain a descriptive/enumerated bubble-text entry
- A user can reasonably determine if there are deeper levels of bubble-text available by the presence of parenthesis or square brackets encapsulating the information following the “tag”. A “tag” and the information that follows is always separated by a colon ‘:’.
| Tag | Name | Description |
|---|---|---|
| !ALERT | Alert Indicator | Prepended to another tag as indicator of important events (commonly to signal an error of some kind) |
| FRAG | Fragmented Packet | Indication of an incomplete ABCC SPI packet detected. |
| SPI_CTL | SPI Control Field | (MOSI) SPI control byte |
| RES | Reserved Field | - |
| MSG_LEN | Message Data Length Field | (MOSI) Length in WORDs (16-bit) of the "Message Data Field" |
| PD_LEN | Process Data Length Field | (MOSI) Length in WORDs (16-bit) of the "Process Data Field" |
| LED_STS | LED Status Field | (MISO) LED status |
| ANB_STS | Anybus Status Field | (MISO) Anybus status |
| SPI_STS | SPI Status Field | (MISO) SPI status |
| APP_STS | Application Status Field | (MOSI) Application status |
| INT_MSK | Interrupt Mask Field | (MOSI) Mask specifies which interrupt events are generated by the module. |
| TIME | Network Time Field | (MISO) Network Time reported from the module |
| MSG_SIZE | Message Size Field | Size of the Message Data Size in bytes. This corresponds to the actual payload of the message which may exceed MSG_LEN, in which case message fragmentation is used. |
| SRC_ID | Message Source ID | Source ID for a message transaction |
| OBJ | Object | Host/Module object being accessed |
| INST | Instance | Instance of the object being accessed |
| CMD | Command Message | - |
| RSP | Response Message | - |
| ERR_RSP | Error Response Message | - |
| EXT | Command Extension | - |
| MD | Message Data | Valid Message Data |
| ERR_CODE | Error Response Code | Indication of an Error Response Code (first byte) |
| -- | Data Not Valid | Indication of "data not valid". Used in leftover message data. |
| PD | Process Data | Indicates either read/write process data |
| CRC32 | CRC32 Checksum | - |
| PAD | Pad Field | (MOSI) Dummy Data |
Each analyzer plugin is responsible for drawing their own markers onto channels; this is an optional feature of a plugin which can be used in a variety of ways to provide higher-level/at-a-glance understanding of a capture or finely detailed indication of events. This plugin uses markers in both ways; the usage of each marker will be described below.
| Marker | SDK Name | Applicable Channels | Usage |
|---|---|---|---|
 |
Start | Enable | Used to indicate an ABCC message command |
 |
Stop | Enable | Used to indicate an ABCC message response (no error) |
 |
Dot | Enable | Used to indicate ABCC message fragmentation |
 |
Square | Enable | Used to indicate that multiple events have occurred (no errors) |
 |
Error Dot | Enable | Used to signal an ABCC error response message. |
 |
Error Square | SCLK, Enable | Used to indicate a clocking/protocol violation or that multiple events have occurred with at least one error event. |
 |
Error X | Enable | Used primarily to indicate an error in the CRC32 field or to signal that a packet has been ”cancelled” from further processing due to byte acquisition error. |
 |
Up Arrow | SCLK | Used to indicate the clock sample phase. |
 |
One | MOSI, MISO | Used to indicate the sample point fed into the byte acquisition logic. In this case a logic ’1’ was read. |
 |
Zero | MOSI, MISO | Used to indicate the sample point fed into the byte acquisition logic. In this case a logic ’0’ was read. |
Note: To help with locating the actual error event, “error markers” (dots, squares, or x’s are placed on the Slave Select signal where the beginning of the bubble-text frame associated with the error event occurred. The current version of Saleae Logic software has some issues with resolving markers that are drawn in close proximity to each other. To work around this issue, such markers are relocated to the slave select line to help maximize the likelihood that the marker will be drawn on the screen. Ideally, a future update of the Logic software would remove this limitation. In such an event, these markers may be relocated to reside on the physical channel where the error event was detected.
The figure below shows the default state of the analyzer settings.
This option allows the plugin to have an awareness of the network type which makes it possible to report network specific details. For example, this feature is used to provide the instance name of each instance in the Network Configuration object. The default state of this option is “Unspecified”.
When enabled, this option will index each “error” event. The default state of this option is “enabled”. To make searching for issues as easy as possible, all error events are prefixed with a “!”. An error is classified as any of the following:
- SPI settings mismatch (CPOL, CPHA, Slave-Select Active Level, etc.)
- Protocol Fragmentation
- Not to be confused with ABCC SPI fragmentation protocol. This error is indicated when Slave-Select de-asserts before a complete ABCC transaction completes.
- SPI Clocking Errors
- Error Response Messages
- Application Status is in an “error state”
- Anybus Status is in an “error state”
When enabled, this option will index each “network timestamp” received from the MISO ABCC message. The default state of this option is “disabled”.
Note: The Saleae Logic software currently does not support adding multiple indexed results to the “Decoded Protocols” sub-window for separate bubble-text entries that exist in the same time-space (even though they reside in separate channels). This means when enabling both “Timestamp Indexing” and “Application Status Indexing” only one entry in the decoded protocols can exist. Currently, priority is given to the “Application Status” events. A future update to the plugin may resolve this limitation.
When enabled, this option will index each “Anybus status event” received from the MISO ABCC message. The default state of this option is “disabled”. Even when disabled, if error indexing is enabled, any Anybus state related to an error/exception will be indexed.
When enabled, this option will index each “Application status event” received from the MISO ABCC message. The default state of this option is “disabled”. Even when disabled, if error indexing is enabled, any application state related to an error/exception will be indexed.
When enabled, this option will index each “New message” in the “Decoded Protocols” sub-window. Retransmissions, commands, and (error) responses all fall into this category. This setting can be set to “compact”, “verbose”, or “disabled”. The default state of this option is “verbose”.
| Entry | MOSI-Obj {03:0001h}, Cmd {01:0003h} |
| Meaning | A new message for object 0x03 (Network object) instance 0x0001 with command byte 0x01 (Get_Attribute) for attribute 0x03 (Data format). To keep things compact (since the Saleae Logic software does not have a resizable decodes window) the message fields are represented in the decoded section as raw hexadecimal format. |
| Entry | MISO-Obj {03:0001h}, Rsp {01:0003h} |
| Meaning | This message is identical to the previous example except that it represents a response message. Notice that the bit-field (within the command byte) responsible for indication of whether a message contains a command or a (error) response is filtered from the raw value here. This is done to improve the flexibility of searching the decoded results. |
| Entry | MOSI-Obj {F8:0001h}, Cmd {01:0006h}++ |
| Meaning | Like the previous example this indicates a new message. The presence of “++” at the end of the entry indicates that this is message is using the ABCC’s SPI fragmentation protocol. |
| Entry | MOSI-{Message Fragment}++ |
| Meaning | Indicates the corresponding message data is a continuation of the ABCC’s SPI fragmentation protocol. The presence of “++” at the end of the entry indicates that this is message is not the “Last Fragment”. An example of this is shown in the figure below. |
This option allows the user to prioritize either the “tag” or the “data” for each message data bubble-text entry.
- “Prioritize Tag”
- Use this option when only interested in knowing where the message data begins and ends within the telegram.
- “Prioritize Data”
- Use this option when interested in seeing each adjacent message data byte.
This option allows the user to prioritize either the “tag” or the “data” for each process data bubble-text entry.
- “Prioritize Tag”
- Use this option when only interested in knowing where the process data begins and ends within the telegram.
- “Prioritize Data”
- Use this option when interested in seeing each adjacent message data byte.
This option can specify an external XML configuration file that contains extra options that may be useful in certain situations. Below is a description of each of these options. The default state of this setting is an empty file path string (this means the default state of the advanced settings will be used).
<?xml version="1.0" encoding="utf-8"?>
<AdvancedSettings>
<!-- "4-wire-on-3-channels" is useful when a 4-wire SPI configuration is used to
interface with the ABCC but only MOSI, MISO, and SCLK are connected to the Logic
analyzer. This mode will ignore timing and CPOL/CPHA requirements that the ABCC's
3-wire mode enforces. -->
<Setting name="4-wire-on-3-channels">0</Setting>
<!-- "3-wire-on-4-channels" is useful when a 3-wire SPI configuration is used to
interface with the ABCC but the user has a spare Logic channel that can be used
as a dummy place holder for placing the markers that the plugin normally applied
to the SPI Enable channel. -->
<Setting name="3-wire-on-4-channels">0</Setting>
<!-- "export-delimiter" allows the user to define a delimiter to use when
using one of the plugin's supported export options. Any single (visible)
character is accepted as a delimiter. A tab-delimiter can be specified
by using "\t" without the quotes. -->
<Setting name="export-delimiter">,</Setting>
<!-- "clocking-alert-limit" provides the user with a way restrict how many
times a "clocking alert" event will be reported by the plugin. This can be
useful in cases were a device's SPI chipselect line may "appear" to toggle
at the same time the SPI clock transitions high after receiving the last
bit in the SPI transaction. This event results in a "clocking alert"
notification. This type of event is more of an informational warning/error
event, and as long as the user understands the reason and accept the behavior
as acceptable, then they may opt to set this setting to a value >=0.
Setting the value to 0 disables the notifcation entirely. While any value
above (datatype is S32) zero will set a maximum count for producing the
notification in the processed results. An invalid value or value <0 indicates
that there is no limit.-->
<Setting name="clocking-alert-limit">-1</Setting>
</AdvancedSettings>| Setting | Datatype | Default state | Meaning |
|---|---|---|---|
| "4-wire-on-3-channels" | BOOL (0/1) | 0 | Disabled, 3-wire mode will be assumed when omitting the plugin's ENABLE channel |
| "3-wire-on-4-channels" | BOOL (0/1) | 0 | Disabled, 4-wire mode will be assumed when assigning the plugin's ENABLE channel |
| "export-delimiter" | STRING | "," | Comma Delimited CSV-files (quotes are not to be included). Only single-character values are accepted. Delimiter must be a visible character. The exception to these two rules is that the user can specify a tab-delimiter via "\t" without the quotes |
| "clocking-alert-limit" | SINT32 | -1 | Unlimited |
This plugin supports several options for exporting the captured/processed data. These options make it possible (after a little data manipulation) to:
- Generate process data graphs
- For instance, the trend of an analog input/output signal could be plotted versus the network time.
- Analyze jitter characteristics related to the signalling of valid/new input data or receiving new output data.
- Collect and assemble message data that was sent using SPI fragmentation
For instance, a file transfer to/from a File System Interface instance could be captured and easily reassembled into a matching file using the exported capture data for verification purposes.
Below is an example of exporting message data during the startup process of the ABCC SDK.
The current generation of Saleae Logic hardware adds analog input functionality and can perform basic analog measurements. This helps in spot-checking signal quality when troubleshooting a new hardware design. When using this functionality, keep in mind that the analyzer has anti-aliasing filters which will smooth out the signal and remove out-of-band high frequency content. Sampling around 10x the signal’s frequency is recommended if any precise measurements are required. For more serious analog measurement, a traditional oscilloscope is recommended; however having digitally decoded SPI communication along side of time-correlated analog waveforms can be invaluable when debugging certain signal quality issues.
In certain cases, the Logic software may report that it cannot keep up using the current sample rate.
To avoid this scenario, try the following:
- Reduce the pre-trigger buffer size (found in Options->Preferences->Capture)
- Reduce the sample rate (as requested by the software)
- Reduce the capture size
- Remove/disable unnecessary channels from capture
- Remove unnecessary USB peripherals from the USB controller that the Logic is connected to.
- Move the Logic hardware to another USB controller
- Replace the USB cable with a shorter and/or higher quality cable. Poor signal quality may introduce bit errors across the USB bus and will require retransmission. Such events may fill up the Logic’s buffer which could result in a buffer overrun.
- Check Saleae Q&A links below for details regarding USB3 host drivers and controllers
For the logic to maintain high sampling rates and large capture sizes, the Logic offloads samples into system memory. This means the Logic software increases in RAM utilization with higher sample rates and larger capture sizes. With the current version of the Logic software, the handling of an “out-of-memory” event is less than graceful. When the Logic software runs out of memory, it will simply cash and all unsaved settings or captures will be lost.
To avoid this scenario, try one or more of the following:
- Reduce capture size
- Reduce sample rate
- Remove/disable unnecessary channels from capture
- Save/Close other capture tabs
- Close down unnecessary applications that are consuming system memory (see operating system’s task manager for details on utilizations)
- Upgrade system memory
As a rough estimate, 3 seconds of 4-channel capture data at 50MSamples/second with a host using 10Mbps SPI (4-wire) and approximately 3000 SPI packets per second that is fully processed through the plugin could consume around 1.2GB of RAM. The more logic transitions there are the more memory will be utilized due to the way the analyzer compresses logic data.