Anybus CompactCom SPI Protocol Analyzer Plugin

Copyright © 2015-2022 HMS Industrial Networks, Inc.

THE CODE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. HMS DOES NOT WARRANT THAT THE FUNCTIONS OF THE CODE WILL MEET YOUR REQUIREMENTS, OR THAT THE OPERATION OF THE CODE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN IT CAN BE CORRECTED.

---

Table of Contents

1. Description
2. System Requirements
3. Precompiled Releases
4. Compile & Install
   • Initial Steps
   • Windows
   • GNU/Linux
   • macOS
5. Generating Releases
6. Documentation
7. Changelog
8. Licenses

---

Description

This plugin, in conjunction with the Saleae Logic hardware and software, provides an easy-to-use interface for analyzing bi-directional (full-duplex) Anybus CompactCom (ABCC) SPI protocol communication.

Each field within an SPI packet is added as a multi-layered bubble-text within the Logic software. Basic markup is displayed when zoomed-out, while more detailed information is displayed when zoomed-in.

The decoded results are indexed and searchable within the Logic software; for even more detail, the user can export the message data or process data to a CSV file to be imported into Excel (or similar) for further analysis. For instance, this functionality may reduce the effort required to extract file data transferred from ABCC object messaging, or to plot a waveform extracted from process data using either local timestamp information or the network timestamps (if supported by the network protocol).

System Requirements

• Saleae Logic Software
  • Recommended Version: 1.2.29
  • Other versions will work so long as Analyzer SDK version 1.1.32 is compatible.
  • NOTE: At this time, Saleae Logic V2 is not supported.
• Saleae Logic Hardware
  • While any of Saleae Logic hardware offerings is expected to be compatible, it is important to consider sample rate limitations of the Logic hardware and what SPI data rate the ABCC host-module communication is using. The absolute minimum requirement for sufficiently sampling the communication is 2x the frequency of the SPI SCLK. The ABCC is able to work over a wide range of clock rates where the maximum is specified at 20MHz. So to be able to support this would require at a minimum the ability to sample at 40MSamples/second. Keep in mind that these analyzers may reduce sample rate depending on how many channels on the analyzer are active, so it is imperative that the hardware is able to sufficiently sample the SPI bus for the number of channels required.
• PC running:
  • Windows 7 through Windows 10
    • NOTE: At this time Window 11 has compatibility issues with version 1.2.29. Version 1.2.40 resolves this compatibility issue but Saleae dropped support for the decoded protocols subwindow for this version. An alternative solution for using 1.2.29 on Windows 11 would be to use WSLg and attach the Saleae Logic interface via usbpid.exe. See How-To: Connect USB devices.
  • Ubuntu 12.04.2+
  • Mac OSX 10.7 Lion+
• USB 2.0 or better
  • Using the Saleae Logic on a dedicated USB controller that matches or exceeds the Logic's supported USB version is recommended for ensuring the best possible sampling performance.

Precompiled Releases

Precompiled plugins and documentation are available here: Plugin Releases

Compile & Install

While tagged releases are provided which contain pre-compiled libraries and associated documentation, the user may still opt to compile the libraries for themselves.

Initial Steps

After cloning this git repository, the user will need to initialize the submodules command in order to fetch the repositories containing the Logic Analyzer SDK. Two copies are used of the same repo, one pointed at the release/master branch and another pointing at the legacy SDK to support debugging.

Example for cloning the repository and fetching/initializing the submodules:

git clone https://github.com/hms-networks/AbccSpiAnalyzer.git
cd AbccSpiAnalyzer
git submodule update --init --recursive

Windows

To compile the project please ensure the additional requirements are met:

DEPENDENCIES: Visual Studio 2019, other versions may also work (project retargeting may be necessary)

NOTE: Express or Community versions of Visual Studio may require additional steps to replace occurrences of #include "afxres.h" with #include "windows.h" or installation of the Visual C++ MFC package (this can be done by modifying the Visual Studio installation and enabling the associated feature).

When compiling the project, please ensure that the correct library is linked for the Windows OS being used. The VS solutions provided are setup with the expectation that the host system will be x64. The solutions are also setup for batch build such that an x64 system can compile all supported build configurations with one request. To access this, right-click the Solution 'AbccSpiAnalyzer' item in the Solution Explorer subwindow to access the context menu and select Batch Build....

Cross-compile for GNU/Linux Operating Systems

Also included in the repository is a simple batch file that can be used to quickly build both the Windows and GNU/Linux libraries via the use of Windows 10 WSL (Windows Subsystem for Linux). Cross-compiling for GNU/Linux requires the same set of dependencies documented below for GNU/Linux.

Custom Visual Studio Projects

If there is a need to create a new Visual Studio project, ensure the linker is configured to include the correct library:

• If using Win64, specify ./sdk/release/Analyzer64.lib in the linker input.
  • The configuration manager has this setup as x64.
• If using Win32, specify ./sdk/release/Analyzer.lib in the linker input.
  • The configuration manager has this setup as Win32.

Once compiled, a file called AbccSpiAnalyzer.dll or AbccSpiAnalyzer64.dll in the either ./plugins/Win32/ or ./plugins/Win64 folder, respectively. Copy this DLL to the user's Saleae Logic software installation in the "Analyzers" folder:

• Example: C:\Program Files\Saleae LLC\Analyzers\AbccSpiAnalyzer.dll

The analyzer is now ready to be used and can be found in the same way that other protocol analyzers are added to the Logic software.

GNU/Linux

• To compile simply run the build_analyzer.py python script. This script will compile the appropriate shared object library based on the host system.

DEPENDENCIES: Python, G++

ADDITIONAL DEPENDENCY: Depending on the system it may also be required to install g++-multilib in order for the python build script to complete without error. This is so a 64-bit system can cross-compile for 32-bit machines.

Once compiled, a file called AbccSpiAnalyzer.so or AbccSpiAnalyzer64.so will reside in the either ./plugins/Linux/ or ./plugins/Linux64 folder, respectively. Copy this shared object to the user's Saleae Logic software installation in the "Analyzers" folder.

macOS

• To compile simply run the build_analyzer.py python script.

DEPENDENCIES: Python, G++

Once compiled, a dynamic library called AbccSpiAnalyzer.dylib will reside in the ./plugins/OSX/ folder. Copy this dynamic object to the user's Saleae Logic software installation in the "Analyzers" folder.

Generating Releases

This section is not typically applicable for most users, but is documented here for completeness. The python script make_release.py will generate the ZIP file used for releases. However to use this without error a user must collect the compiled library files for each platform. On a Windows 64-bit host with Ubuntu bash on Windows using WSL (Windows Subsystem for Linux), it is possible to generate all required library files with the exception to macOS using cross_compile.bat. Obtaining the macOS dynamic library is a separate manual step, transferring the dylib from the macOS build host to the Windows host.

Windows:

py.exe -3 -m pip install -r py_requirements.txt
py.exe -3 ./make_release.py

macOS/Linux:

python3 -m pip install -r py_requirements.txt
python3 ./make_release.py

Documentation

For complete details regarding this plugin's functionality please consult the Wiki found within this repository or Quick Start Guide included in this repository's documentation folder. The Wiki is expected to contain more up-to-date details on the plugin's functionality in reference to the master branch whereas the PDF document will typically be updated when a new tagged release is made and is provided as part of the tagged release's downloadable assets.

For details on the Logic SDK's API please refer to the Saleae's Protocol Analyzer SDK page.

Changelog

Please see CHANGELOG.md provided within this repository for details on the changelog history.

Licenses

Please see LICENSE.md provided within this repository for details on the software licensing.