Package: saleae-enrichable-analyzer
Python Tools for Enrichable Saleae AnalyzersThe built-in analyzers for the Saleae Logic provides you with only a few basic options for how to display the transferred bytes -- as ascii text, or in one of several numeric formats.
What if you're working with an device that encodes more than just integer or text data into those bytes, or even stores multiple values in each byte that will require you to either do the math in your head, export the data for post-processing, or display the frame as binary bits so you can directly look at the parts that matter to you?
That's the sort of thing computers are great at doing; why don't we just let your computer do that?This Python library -- in tandem with special "Enrichable" versions of Saleae Logic analyzers -- makes it easy for you to enrich the data displayed so you can provide your own text and markers to display for each frame.
Now you can focus on solving your actual problem instead of interpreting inscrutible hex values.Relatedsaleae-enrichable-spi-analyzer: A version of the Saleae SPI analyzer that supports enrichment.saleae-enrichable-i2c-analyzer: A version of the Saleae I2C analyzer that supports enrichment.InstallationNote: This requires Python 3.5!If you want to use the latest release; just install directly from pypi:pip install saleae_enrichable_analyzerTo use the development version, just clone this repository and run:pip install .Bundled enrichment scriptsThis library is bundled with a handful of enrichment scripts out-of-the-box;
you can use any of these by following the instructions below.
Note that you may need to replacepythonin the examples with the path to the relevant Python binary --
if you installed this library into a virtual environment, that path should point to that environment'spython, of course.SPISC16IS75xxSupports the NXP SC16IS75xx series of SPI UART chips.Known supported:SC16IS740SC16IS750SC16IS752SC16IS760SC16IS762Usable by using the following enrichment script:python -m saleae_enrichable_analyzer.scripts.spi.SC16IS75xxI2CAD799xSupports the Analog Devices AD799x series of I2C ADC chips.Known supported:AD7991 (12 bit)AD7995 (10 bit)AD7999 (8 bit)Usable by using the following enrichment script; be sure to replaceBITSwith the number of bits your ADC provides, andADDRESSwith
your device's base-2 I2C address:python -m saleae_enrichable_analyzer.scripts.i2c.AD799x ADDRESS BITSAdditionally, you can provide the--reference-voltage=VOLTAGEargument
to display the calculated voltage as well as the raw ADC value.INA219Supports the Texas Instruments INA219 current monitor IC.Usable by using the following enrichment script; be sure to replaceADDRESSwith your device's base-2 I2C address:python -m saleae_enrichable_analyzer.scripts.i2c.INA219 ADDRESSWriting your own Enrichment ScriptUsing this is as simple as creating your own module somewhere that subclassessaleae_enrichable_analyzer.EnrichableAnalyzerwith methods for the features you'd like to use;
here is a basic example:importsysfromtypingimportList,Optionalfromsaleae_enrichable_analyzerimport(Channel,EnrichableAnalyzer,Marker,MarkerType)classMySimpleAnalyzer(EnrichableAnalyzer):defhandle_bubble(self,packet_id:Optional[int],frame_index:int,start_sample:int,end_sample:int,frame_type:int,flags:int,direction:Channel,value:int)->List[str]:return["This message will be displayed above every frame in the blue bubble"]defhandle_marker(self,packet_id:Optional[int],frame_index:int,sample_count:int,start_sample:int,end_sample:int,frame_type:int,flags:int,mosi_value:int,miso_value:int)->List[Marker]:markers=[]if(miso_value==0xff){# This will show a "Stop" marker on the zeroth sample# of the frame on the MISO channel when its value is 0xff.markers.append(Marker(0,Channel.MISO,MarkerType.Stop))}returnmarkersif__name__=='__main__':MySimpleAnalyzer.run(sys.argv[1:])The methods described below can be implemented for interacting with Saleae Logic.If you'd like to see simple concrete examples,
you can refer to the following:simple_SC16IS7xx.py: Implements a simple enricher for displaying register, channel, and data for the SC16IS7xx series of SPI UARTs.simple_ad7995.py: Implements a slightly-more completed enricher for displaying detailed configuration and read data for the AD7995 I2C ADC.Also be aware that thescriptsdirectory contains examples, too,
but they may be somewhat more advanced in functionality.handle_bubbledefhandle_bubble(self,packet_id:Optional[int],frame_index:int,start_sample:int,end_sample:int,frame_type:int,flags:int,direction:Channel,value:int)->List[str]:return[]Set the bubble text (the text shown in blue abov the frame) for this frame.
By default, no bubble is shown.  It is recommended that you return multiple
strings of varying lengths.handle_markerdefhandle_marker(self,packet_id:Optional[int],frame_index:int,sample_count:int,start_sample:int,end_sample:int,frame_type:int,flags:int,value1:int,# SPI: MOSI; I2C: SDAvalue2:int,# SPI: MISO; I2C: Undefined)->List[Marker]:return[]Return markers to display at given sample points.
By default, no markers are displayed.This method can be implemented for reasons other than wanting to display
markers, too --
it is useful if your script needs to receive all frames of data in the order they were received.
In such cases, you can record your packets in the body of the method,
and return an empty list.
See thebase I2CAnalyzer classfor a concrete example of that strategy in use.handle_tabulardefhandle_tabular(self,packet_id:Optional[int],frame_index:int,start_sample:int,end_sample:int,frame_type:int,flags:int,value1:int,# SPI: MOSI; I2C: SDAvalue2:int,# SPI: MISO; I2C: Undefined)->List[str]:return[]Data to display in the tabular "Decoded Protocols" section.
Due to limitations within Saleae logic: if implemented, this method must return exactly the same number of strings in the result array for each request;
if you attempt to do otherwise, you may see the following error (sic) "Error: Number of strings in the analyzer results are diffrenet for different display bases" followed by a SIGSEGV.Debugging your enrichment scriptIf Saleae Logic crashes when using your enrichment script,
it's almost certainly the fault of your script and not Saleae Logic.
Luckily, debugging is quite easy by using the built-in logging features.By default, logging is written to stderr,
but given that most of us do not run Saleae Logic in a terminal, that output isn't immediately visible.
To see that logging output without running in a terminal,
you can use the following two flags:--loglevel=LEVEL: Set the level of reported output.
When debugging, you likely want to use--loglevel=DEBUG.
Valid options (in order of increasing verbosity) includeCRITICAL,ERROR,WARNING,INFO, andDEBUG.
The output displayed for a selected level includes the output of all
lower-verbosity levels.--logpath=PATH: Set a file path to write your logging output to.Note that these flags must follow the module name when using a bundled enrichment script.
For example, to debug the bundled AD799x enrichment script (which itself requires two positional arguments),
you can set the following for your "Enrichment Script" in Saleae Logic:python -m saleae_enrichable_analyzer.scripts.i2c.AD799x --loglevel=DEBUG --logpath=/tmp/logic_debug.log 12 0101000If you're debugging a script you've written, though,
simply provide the flags following your script path:python /path/to/your/enrichment/script.py --loglevel=DEBUG --logpath=/tmp/logic_debug.logLogging messages will continue to be written to stderr regardless of whether you've enabled logging to a file,
and if you find that the logging output written by your script is not revealing,
it may be helpful to run Saleae Logic in a terminal to see both the logging output of Saleae Logic and your script interleaved.