Saleae provides a analyzer SDK which can be used to develop custom protocol decoding plugins in C++.
You can find the SDK downloads here: Protocol Analyzer SDK
Newer versions of the Saleae software cannot be used to debug custom analyzers. This means that older versions of the software and SDK must be used if you wish to attach a debugger and step through your code.
Note: it is impossible to attach a debugger to any version of the software that supports the new products. We are working on a solution to this problem, but for now that means you must rely on the simulation data generator for your analyzer to produce captures you can then debug in the older software.
To debug your custom analyzer, we recommend you use the 1.1.14 SDK with the 1.1.18 software. Because older versions of the software and SDK are 32 bit only, you will only be able to compile for 32 bit initially. Later, when you port the analyzer to the latest version of the SDK, you will be able to compile for 32 bit and 64 bit.
Download the 1.1.14 SDK. Download the 32 bit stand-alone copy of the 1.1.18 software. The 32 bit standalone copy is required because the normal installer will not let you install the 32 bit software on a 64 bit operating system.
Logic 1.1.18, 32 bit stand-alone: http://downloads.saleae.com/betas/1.1.18/Logic1.1.18BetaWin32Standalone.zip
You can then follow the instructions provided with the SDK to setup a visual studio project for your new analyzer. Note that any version of visual studio from 2008 or newer that supports C++ can be used. The included documentation also covers how to debug the software.
If you use the 64 bit version of the Logic software, you will see an error message when the software loads your custom analyzer saying that the dll is not a valid Win32 Application. You will need to use the 32 bit software to load your analyzer.
Updating to the latest SDK Once you complete debugging of your analyzer, you will want to port it to the latest SDK, which is version 1.1.32: http://downloads.saleae.com/betas/1.1.32/SaleaeAnalyzerSdk-1.1.32.zip
This version of the SDK includes the 32 bit and 64 bit libraries. Please make sure to build for 64 bit if you are using a 64 bit computer.
Note (updated): Software releases 1.2.2 and 1.2.3 on Windows dynamically linked against the msvc C and C++ runtimes, breaking compatibility with the analyzer SDK. This was fixed in 1.2.4 and all following releases. Analyzers built from the 1.1.32 SDK work just fine with the latest beta software.
Porting source code
To port your analyzer to the new SDK, you need to make two changes. First, your main Analyzer class needs to inherit from Analyzer2 instead of Analyzer. This adds a new public virtual function SetupResults(). You need to implement this function. This function handles the setup that you previously did at the beginning of the WorkerThread() function. This change was made so that initialization of the results class could be done on the main thread before the analyzer thread was started. Specifically, this includes calling reset on mResults, calling SetAnalyzerResults, and registering channels with AddChannelBubblesWillAppearOn. Do not call GetAnalyzerChannelData, that still needs to be done in the WorkerThread, because the call may block until data is available to process.
Second, the new SDK adds support for protocol search results, which is a new feature in the software. In your AnalyzerResults class, update your GenerateFrameTabularText function. This function was previously unused in the older SDK, and the default implementation should NOT be used. At the very least you should call ClearTabularText(); The previous sample code called ClearResultStrings(), which SHOULD NOT BE CALLED in the new version. You can optionally add one or more text strings per frame to the protocol results view by calling AddTabularText(); Generally 1 string per frame is recommended.
Again, be sure to build the newly ported analyzer for 64 bit if you plan to use this on a 64 bit operating system. Note that you will not be able to attach the visual studio debugger to the newer Logic software, so you will not be able to directly debug your new analyzer.
Instructions to switch between x32 and x64 targets in VS can be found here. The instructions are the same for all newer versions of VS too.
If you have any problems with the above instructions, please contact support.
Common issues on Windows
- The software says "Unable to 'LoadLibrary' on dll ... is not a valid Win32 application" This is most likely because the analyzer was not built for the same platform architecture as the software running it. In almost all cases, this means the analyzer was compiled for 32 bit instead of 64 bit. Details to switch from 32 bit to 64 bit are included in the Analyzer SDK documentation on page 9. First, add a x64 target to your project. Then, edit the linker settings for the 64 bit configuration. Change the additional dependencies item from Analyzer.dll to Analyzer64.dll. Note: Only the software versions 1.1.16 and later were built for 64 bit. Previous releases, including 1.1.15, were 32 bit only, which is why no 64 bit analyzer dll was provided.
- The Saleae software crashes on launch when the debugger is attached. Versions after about 1.1.18 no longer allow debuggers to attach. In these cases, we recommend building with the 32 bit version of the 1.1.18 beta and the 1.1.14 SDK, and debug there. This restriction only applies to Windows.
OS X and Linux Development
OS X and Linux do not have the same debug issues, nor does the latest release have the same library linking problem. You can develop your analyzer using the latest SDK (1.1.32) and the latest beta (currently 1.2.3) With no need to use older versions.
Saleae assistance for building analyzers
If you have any trouble building your own analyzer, or another analyzer you found online, please let us know. Please also send us a link to the source code, preferably posted on github, or another open source git repository. Ideally, please use the format described here: Best practices for sharing custom Analyzer projects with the community and with Saleae support
If you would like us to build it for you, please let us know what platform(s) you would like it built for. If you would like help with bugs or other issues, please send us a description of the problem, and send us an open source github link that we can fork, fix it there, and then submit a pull request.
We can only offer this service when we have enough time to do it, and we might not always have that time.
trello ID: 55f21397cf176b495de94c25