High-Level Analyzer (HLA) Extensions

This guide assumes that you have familiarity with the Python programming language. It is what will be used to customize our HLA.

Overview#

This guide assumes you have generated a new High-Level Analyzer. In this guide you will learn about:

1. The files included in the HLA template extension and what they are.
2. The different parts of HighLevelAnalyzer.py.
3. How to process input analyzer frames and output new analyzer frames.

High Level Analyzer Files#

In your new High Level Analyzer (HLA) extension folder you will find 3 files:

• README.md
  • Documentation for your extension, shown within Logic 2 when you select an extension, and what users will see if you put your extension on the Marketplace.
• extension.json
  • Every extension must have this file in its root directory.
  • Contains metadata about the extension, and the HLAs and Measurement scripts that are included with the extension.
  • See Extension File Format for more information.
• HighLevelAnalyzer.py
  • Python source code for your HLA.

For the purposes of this document, we will be focusing on HighLevelAnalyzer.py

HighLevelAnalyzer.py Breakdown#

Let's break down the contents of HighLevelAnalyzer.py .

# HighLevelAnalyzer.py
from saleae.analyzers import HighLevelAnalyzer, AnalyzerFrame, StringSetting, NumberSetting, ChoicesSetting

class MyHla(HighLevelAnalyzer):

    # Settings:
    my_string_setting = StringSetting()
    my_number_setting = NumberSetting(min_value=0, max_value=100)
    my_choices_setting = ChoicesSetting(['A', 'B'])

    # Output formats
    result_types = {
        'mytype': {
            'format': 'Output type: {{type}}, Input type: {{data.input_type}}'
        }
    }

    # Initialization
    def __init__(self):
        print("Settings:", self.my_string_setting,
              self.my_number_setting, self.my_choices_setting)

    # Data Processing
    def decode(self, frame: AnalyzerFrame):
        return AnalyzerFrame('mytype', frame.start_time, frame.end_time, {
            'input_type': frame.type
        })

Imports#

from saleae.analyzers import HighLevelAnalyzer, AnalyzerFrame, StringSetting, NumberSetting, ChoicesSetting

Declaration and Settings#

All HLAs must subclass HighLevelAnalyzer, and additionally output AnalyzerFrames. The Setting classes are included so we can specify settings options within the Logic 2 UI.

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(['A', 'B'], label='My Choice')

This declares our new HLA class, which extends from HighLevelAnalyzer, and 3 settings options that will be shown within the Logic 2 UI. Note: if the name of the class MyHla() is used it must be referenced in the accompanying json file. Note that Hla() is the default value.

Output Formats#

result_types = {
        'mytype': {
            'format': 'Output type: {{type}}, Input type: {{data.input_type}}'
        }
    }

This specifies how we want output AnalyzerFrames to be displayed within the Logic 2 UI. We will come back to this later.

Initialization#

def __init__(self):
        print("Settings:", self.my_string_setting,
              self.my_number_setting, self.my_choices_setting)

This is called when your HLA is first created, before processing begins. The values for the settings options declared at the top of this class will be available as instance variables here. In this case, the settings values will be printed out and visible within the Logic 2 terminal view.

Data Processing#

def decode(self, frame: AnalyzerFrame):
        return AnalyzerFrame('mytype', frame.start_time, frame.end_time, {
            'input_type': frame.type
        })

This is where the bulk of the work will be done. This function is called every time the input to this HLA produces a new frame. It is also where we can return and output new frames, to be displayed within the Logic 2 UI. In this case we are outputting a new frame of type 'mytype', which spans the same period of time as the input frame, and has 1 data value 'input_type' that contains the value of the type of the input frame.

What's Next?#

• Find out about other analyzers and the AnalyzerFrames they output in the Analyzer Frame Types documentation.
• Use the API Documentation as a reference.
• Browse the Saleae Marketplace in Logic 2 for more ideas and examples of extensions you can create.
• Publish your extension to the Saleae Marketplace!