Automation API -- Documentation for Low Level Analyzer Settings

I’m starting to investigate the Automation API, specifically on details about adding an analyzer to the capture.

I found the Automation API documentation:

… which for add_analyzer() says:

  • settings (Optional[Dict[str, Union[str, int, float, bool]]]) – All settings for the analyzer. The keys and values here must exactly match the Analyzer settings as shown in the UI, defaults to None

However, I didn’t find where the specific keys and values are actually documented?

For HLAs, I believe this information can be retrieved from the Python source code, but for LLAs it is not as straight forward to easily extract this information. A tentative work around that I think might work is to add the low level analyzer to a capture, then create and export the ‘preset’ settings file (*.logic2Preset).

Inspecting this preset (JSON) file shows:

  • a (list of) analyzers each comprised of settings, each comprised of:
    title (use for the add_analyzer() settings key … ?)
    setting (use use for the add_analyzer() settings value … ?)

However, I didn’t find it documented how to map these properties to the appropriate type (e.g., [str, int, float, bool]), so it may take some trial and error to figure it all out. Otherwise, is there a better way to extract this information? Is this information already documented somewhere that I missed?

Note: the provided has an example for SPI (spi_analyzer):

        # Add an analyzer to the capture
        # Note: The simulator output is not actual SPI data
        spi_analyzer = capture.add_analyzer('SPI', label=f'Test Analyzer', settings={
            'MISO': 0,
            'Clock': 1,
            'Enable': 2,
            'Bits per Transfer': '8 Bits per Transfer (Standard)'

… but it didn’t cover all the SPI settings available in the GUI:

  • MOSI
  • MISO
  • Clock
  • Enable
  • ‘Significant Bit’
  • ‘Bits per Transfer’
  • ‘Clock State’
  • ‘Clock Phase’
  • ‘Enable Line’

Likewise, it isn’t 100% clear what the ‘default’ value might be (or which settings are r, if it is NOT explicitly specified – which I assume will be an LLA specific choice for each setting.

As per the Analyzer SDK API documentation, the possible Analyzer Settings Interfaces Objects are as follows:

  • AnalyzerSettingInterfaceChannel - Used exclusively for input channel selection.
  • AnalyzerSettingInterfaceNumberList - Used to provide a list of numerical options for the user to choose from. Note that this can be used to select from several enum types as well, as illustrated below. (Each dropdown below is implemented with its own interface object)
  • AnalyzerSettingInterfaceInteger - Allows a user to type an integer into a box.
  • AnalyzerSettingInterfaceText - Allows a user to enter some text into a textbox.
  • AnalyzerSettingInterfaceBool - Provides the user with a checkbox.

… but it seemed like AnalyzerSettingInterfaceNumberList was specified using the string (dropdownText) rather than the integer (value) format?

Anyway, for more complete documentation – it would be nice to have a list of all the officially supported low level analyzers and the exact syntax for key and value(s) to use for the settings parameter.

Also, I recognize that the HLAs are considered ‘external extensions’ vs. natively supported, so I think it’s fair to look in the HLA’s source file(s) directly (unless any are natively supported in the future).

For example, I understand the HLA Setting classes (i.e., StringSetting, NumberSetting, or ChoicesSetting) would define the key (label …?) and value to use for the settings parameter in add_high_level_analyzer() API, as per the example from High-Level Analyzer (HLA) Extensions:

class MyHla(HighLevelAnalyzer):
    my_string_setting = StringSetting(label='My String')
    my_number_setting = NumberSetting(label='My Number', min_value=0, max_value=100)
    my_choices_setting = ChoicesSetting(label='My Choice', ['A', 'B'])

@BitBob Sorry for the confusion around the add_analyzer() settings values!

We don’t have the exact analyzer settings documented, however, the idea was that the exact text can be grabbed directly from the UI. This allows us to not have to maintain documentation for when settings names changes.

You brought up a good point about our spi_analyzer setup in our Automation API example. When a setting isn’t specified, the ‘default’ value will be implemented. The ‘default’ value can be determined in the UI as well. Specifically, you can open up the SPI analyzer settings, and hit the Reset button at the bottom-left to determine that analyzer’s default settings.

Thanks for the response; unfortunately, the UI doesn’t appear to let you to copy/paste the text out of the UI directly, but it appears the preset JSON file (*.logic2Preset file from exporting settings) does have the requested information encoded within it.

So, I think the info can be extracted from this file, if there aren’t any plans to publish any equivalent documentation? I understand how it can be a challenge to keep documents up-to-date, so unless there’s a way to extract it automatically from the source code, then maybe it’s not a worthwhile activity for Saleae to pursue – as fully documenting all these details could become obsolete/inaccurate as the various analyzer settings evolve.

However, maybe the basic internal information could be documented, such as a general mapping of the LLA/HLA ‘setting type’ to the corresponding Automation SDK setting key/value dict pair?

In particular, can the AnalyzerSettingInterfaceNumberList setting use both the dropdownText (or str parameter for AddNumber() function) and the corresponding float (or double) value, or is it ONLY the dropdownText value from the GUI?

Note: the add_analyzer() documentation in the Automation API indicated that settings could be one of {str, int, float, bool} – but it seems like float isn’t actually used right now (??)

So, here’s what I think is the right mapping – @timreyes can you please confirm/clarify?

Setting types for LLAs from Low Level Analyzer Settings (Analyzer SDK):

  • AnalyzerSettingInterfaceChannel
    key: title, value: <int> from Get/SetChannel()
    (JSON:*.logic2Preset) key: title, value: value
  • AnalyzerSettingInterfaceNumberList (??)
    key: title, value: <str> from AddNumber():str parameter (and/or <float> from Get/SetNumber()) (??)
    (JSON:*.logic2Preset) key: title, value: dropdownText (and/or value … ??)
  • AnalyzerSettingInterfaceInteger
    key: title, value: <int> from Get/SetInteger()
    (JSON:*.logic2Preset) key: title, value: value
  • AnalyzerSettingInterfaceText
    key: title, value: <str> from Get/SetText()
    (JSON:*.logic2Preset) key: title, value: value
  • AnalyzerSettingInterfaceBool
    key: title, value: <bool> from Get/SetValue()
    (JSON:*.logic2Preset) key: title, value: value (true or false)

Note: the title above is from SetTitleAndTooltip() Analyzer SDK API call for each AnalyzerSettingInterface type listed above.

Setting types for HLAs from High Level Analyzer Extensions API:

  • StringSetting
    key: label, value: <str>
  • NumberSetting
    key: label, value: <int>
  • ChoicesSetting
    key: label, value: <str> (??)

Note: the label above (for key) is based on the HLA python call of corresponding Setting() API call, and the value is based on what user would want to set in each corresponding setting.

Finally, maybe there is something from the core Logic code that exports these settings (presets) that could also help ‘auto-generate’ the requested documentation – as it seems like it is encoded in the JSON file as described above. E.g., for each AnalyzerHandle (LLA or HLA) supported by the Automation API – dump the corresponding (list of) AnalyzerSettingInterface (or python equivalent) objects to show the key/value (and default) settings list (??)

Otherwise, maybe just confirming the methods described above are the best way to ‘reverse engineer’ the necessary information, in lieu of any additional documentation being created by Saleae in order to have all the possible ‘exact’ settings available up front :wink: