API Reference for Interface and Protocol Projects

The Semiconductor Device Control Add-On Professional edition for InstrumentStudio includes APIs in the interface and protocol project templates to create communication interfaces.

Table 25. Interface API
API Call Description
Constructor

Instantiates the interface and is the entry point of the Interface class. The constructor has the following required fields and properties:

  • InterfaceSettingsByName
  • InterfaceDynamicSettingsByName
  • InterfaceSettingsValidationStatus
  • InterfaceDynamicSettingsValidationStatus

The InterfaceSettingsByName and InterfaceDynamicSettingsByName dictionaries are instantiated with the required setting values. 
Run()

Triggered when you click the Start button in the Semiconductor Device Control Add-On.

The generated code has a default logic that updates and validates the interface settings and throws out any error with the setting values to ensure that the communication cannot start if settings are invalid.

This method creates the instrument instance and defines the presets for the instrument.
Stop()

Triggered when you click the Stop button in the Semiconductor Device Control Add-On.

This method closes sessions and disconnects used pins.
GetDeviceInformation()

Called from the Semiconductor Device Control Add-On to get the resource and pin map details configured in the interface settings. This method returns the .pinmap file path and the resource name of the instrument configured in the pin map.
GetInterfaceSettings()

Called from the Semiconductor Device Control Add-On to display the settings in the configuration page.

Do not modify this method.
GetInterfaceDynamicSettings()

Called after communication starts to display the dynamic settings in the configuration page.

Do not modify this method.
UpdateAndValidateInterfaceSettings()

Updates the interface settings with modified setting value.

This method also validates the newly updated setting value whenever you change the setting.

If there are any validation errors, the errors update to the InterfaceSettingsValidationStatus dictionary.

This method returns an error if the InterfaceSettingsValidationStatus dictionary contains any error information.
UpdateAndValidateInterfaceDynamicSettings()

Updates the interface settings with the modified setting value.

This method also validates the newly updated setting value whenever you change the setting.

If there are any validation errors, the errors update to the InterfaceDynamicSettingsByName dictionary.

This method returns an error if the InterfaceDynamicSettingsByName dictionary contains any error information.
Table 26. Protocol API
API Call Description
Constructor

Instantiates the protocol class. This is triggered when a new protocol is created in Semiconductor Device Control Add-On.

The protocolSettingsByName and protocolDynamicSettingsByName dictionaries are instantiated here. They contain the static and dynamic settings of the protocol that are populated on the configuration page of the Semiconductor Device Control Add-On for the specific protocol.

The ProtocolSettingsValidationStatus and DynamicSettingsValidationStatusByName dictionaries are instantiated here. These dictionaries store the validation status of the static and dynamic settings. Any error in the protocol settings is added to these dictionaries and populate in the UI.
Run()

Triggered when the user clicks the start button in the Semiconductor Device Control Add-On.

The generated code has a default logic in this method that updates and validates the protocol settings and throws out any error with the setting values. This ensures that communication cannot be started when settings are invalid.

This method defines the presets for the protocol.
Stop()

Triggered when the user clicks the stop button in the SDC UI.
GetProtocolSettings()

Called from the UI to display the settings in the configuration page.
GetProtocolDynamicSettings()

Called after communication displays the dynamic settings in the configuration page.
UpdateAndValidateProtocolSettings()

Updates the protocol settings with the modified setting value and validates the updated setting value.

This method has the following code sections:

  • In Settings Update, the code snippet updates the modified setting value in the template provided. You can insert logic into this snippet for setting changes that result in additional protocol setting changes.
  • In Settings Validation, the code snippet that iterates through all the static protocol settings is added to the template. You can perform the validation logic in the switch case provided and add the error message to ProtocolSettingsValidationStatus.
UpdateAndValidateDynamicSettings()

Updates the protocol dynamic settings with the modified setting value and to validate the updated setting value.

This method has the following code sections:

  • In Settings Update, the code snippet updates the modified setting value in the template provided. You can insert logic into this snippet for setting changes that result in additional protocol setting changes.
  • In Settings Validation, the code snippet that iterates through all the dynamic protocol settings is added to the template. You can perform the validation logic in the switch case provided and add the error message to DynamicSettingsValidationStatusByName.
WriteRegisterData()

Called when you write a register or field from the UI or API layer.

You can define protocol logic to write the register data in this method.

This method returns a generic “Result” structure of type BitArray. The code snippet given in the method instantiates the return type structure and returns the object. This can be used to send values and error information back to the Semiconductor Device Control Add-On.
ReadRegisterData()

Called when you read the register or field from the UI or API layer.

You can define their protocol logic to read the register data in this method.

This method returns a generic “Result” structure of type BitArray. The code snippet given in the method instantiates the return type structure and returns the object. This can be used to send values and error information back to the Semiconductor Device Control Add-On.
Note The NI657x protocol template contains all the APIs in the previous table in addition to the following APIs that are specific to NI657x protocols.
Table 27. NI657x Protocol API
API Call Description
CreateWriteWaveforms()

Defines the source waveform data for the write register operation.

The method has the register address and register data information. Use this method to create the source waveform data as per the bit pattern defined for the protocol.

By default, logic is provided for the source waveform requirements of the example pattern included with the template.
CreateReadWaveforms() Defines the source waveform data for the read register operation.

The method has the register address and register data information. Use this method to create the source waveform data as per the bit pattern defined for the protocol.

By default, logic is provided for the source waveform requirements of the example pattern included with the template.
EncodeErrorDetectionBits()

Adds error detection bits, such as parity or CRC, to the source waveform data created.

This method is optional and can be modified based on the requirement.

By default, the logic in the method returns only the source waveform data without any modifications.
DecodeReadData()

Decodes the read data and verifies if the data is valid based on the error detection bits, such as parity or CRC.

The method returns the read data after stripping the error detection bits from the data.

This method is optional and can be modified based on the requirement.

By default, the method returns the read data and assumes that the data is valid.
ProcessReadData()

Processes the read data and convert it to a format that can be returned to the Semiconductor Device Control Add-On.

By default, the logic in the template acquires the decoded data from the DecodeReadData() API and applies the appropriate bit/byte order and sample width.

This method is optional and can be modified based on the requirement. The default logic is sufficient for most use cases.