Host Interface

class client.HostPythonIntf

Bases: object

This class encompasses all the methods required to interact with the capture client.*

The capture client can operate locally when using the Exostiv probe, or remotely when using the Exostiv Blade.

For examples of how to use these methods, please refer to the examples section.

class OutputEquation

Bases: object

Output equation configuration.

Variables:

  • and_invert – Invert the output of the AND equation.

  • or_invert – Invert the output of the OR equation.

  • combine_type – Combination type for the AND and OR equation outputs (see OutputEquationCombineTypes class).

  • combine_invert – Invert the output of the combined equations.

  • use_qualification – Filter the trigger with the qualification equation.

class OutputEquationCombineTypes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The output equation can use AND or OR logic.

AND = 0
OR = 1
class TransferMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Defines how the IP transfers data over the high speed link.

Possible values

  • Burst : data is transferred in bursts

  • Stream : data is transferred continuously

  • Unknown : transfer mode is not defined

Burst = 0
Stream = 1
Unknown = -1
class TriggerCounterType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Defines the capture counter type.

Possible values

  • Trigger : counter for triggering logic

  • Qualification : counter for qualification logic

Qualification = 1
Trigger = 0
class TriggerFunction(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Trigger functions can be combined with AND or OR logic.

AND = 0
OR = 1
class TriggerOperation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Defines the logical operations available for the signals used in the trigger equation.

Equal = 0
InRange = 6
Larger = 2
LargerOrEqual = 4
NotEqual = 1
NotInRange = 7
Smaller = 3
SmallerOrEqual = 5
Unknown = -1
class TriggerRadix(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Radixes usable with the trigger equations.

Possible values

  • Bin : binary

  • Dec : decimal

  • Hex : hexadecimal

  • SDec : signed decimal

Bin = 0
Dec = 1
Hex = 3
SDec = 2
class TriggerType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Defines whether a capture unit is used for triggering of data qualification.

Qualification = 1
Trigger = 0
class WavesExportFormat(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Format used when exporting waves.

Possible values

  • Bin : binary

  • Csv : comma separated values

  • CsvDiff : transitions only, comma separated values

  • Vcd : value change dump

Bin = 0
Csv = 1
CsvDiff = 2
Vcd = 3
class WavesExportRadix(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Radix used when exporting waves.

Possible values

  • Bin : binary

  • Hex : hexadecimal

  • UInt : unsigned integer

Bin = 0
Hex = 1
UInt = 2
class WavesExportSamples(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Samples exported when exporting waves.

Possible values:

  • AllSamples : all sampled data

  • VisibleSamples : only the samples visible in the waveform viewer

  • RangeOfCapture : range of captures

  • RangeOfSamples : range of samples

AllSamples = 0
RangeOfCapture = 2
RangeOfSamples = 3
VisibleSamples = 1
add_trigger(signal_name)

Add a trigger to the current capture unit equation.

Parameters
signal_namestr

Signal name.

Returns
int

0 on success, error code otherwise.

capture_download_data(capture_unit)

Start manually downloading the sampled data. This method is only useful when the automated data download has been disabled with method ‘set_manual_data_download’.

Parameters
capture_unitstr

Capture unit name.

Returns
int

0 on success, error code otherwise.

capture_start(capture_unit, forced=False)

Starts a new capture. If argument ‘forced’ is set to True, the capture will start immediately, otherwise it will start on one or more trigger events.

Parameters
capture_unitstr

Capture unit name.

forcedbool, optional

Don’t wait for a trigger if True, by default False.

Returns
int

0 on success, error code otherwise.

capture_start_multi(capture_unit_list, forced=False)

Starts a new capture on multiple capture units simultaneously. If argument ‘forced’ is set to True, the capture will start immediately, otherwise it will start on one or more trigger events.

Parameters
capture_unit_liststr=[]

List of capture unit names.

forcedbool, optional

Don’t wait for a trigger if True, by default False.

Returns
int

0 on success, error code otherwise.

capture_stop(capture_unit)

Stops the currently running capture. The already captured data will be downloaded.

Parameters
capture_unitstr

Capture unit name.

Returns
int

0 on success, error code otherwise.

capture_stop_multi()

Stops all the currently running captures. The already captured data will be downloaded.

Returns
int

0 on success, error code otherwise.

close_project()

Closes the current project file.

Returns
int

0 on success, error code otherwise.

connect_blade(ip_address, user_name, user_password)

Connect to an Exostiv Blade. (Blade only)

Parameters
ip_addressstr

Blade IPv4 address in the for xxx.xxx.xxx.xxx. Example : 192.168.0.100.

user_namestr

Username. The username must be defined on the Blade beforehand.

user_passwordstr

Password. The password must be defined on the Blade beforehand.

Returns
int

0 on success, error code otherwise.

connect_ip()

Connect to the Exostiv IP and wait for the link to come up. (Blade only)

Returns
int

0 on success, error code otherwise.

connect_session(uuid)

Connect to a session. A session matches one QSF connector on the capture board. (Blade only)

Parameters
uuidint

Session identification number.

Returns
int

0 on success, error code otherwise.

delete_blade_files(files)

Delete a list of file on Exostiv Blade. The file name must have the following structure HOME/<user login>/<session id>/<logical unit id>/<file name>. (Blade only)

Parameters
filesstr=[]

List of files to delete.

Returns
int

0 on success, error code otherwise.

disconnect_blade()

Disconnect from the currently connected Exostiv Blade. (Blade only)

Returns
int

0 on success, error code otherwise.

disconnect_ip()

Disconnect from the Exostiv IP. This method is called automatically when the client object is deleted. Hence, the user should never use this method. (Blade only)

Returns
int

0 on success, error code otherwise.

disconnect_session()

Disconnect from the current session. (Blade only)

Returns
int

0 on success, error code otherwise.

export_waves(file_name, wave_names=None)

Export waves to file ‘file_name’.

Parameters
file_namestr

Output file name.

wave_namesstr=[], optional

A string list of signal names to export, by default None. All signals are exported when ‘wave_names’ is not defined.

Returns
int

0 on success, error code otherwise.

get_blade_file(src_file, dst_file, remove_file=False)

Download a file from Exostiv Blade to the user system. (Blade only)

Parameters
src_filestr

Source file on Exostiv Blade. The path has the following structure: HOME/<user login>/<session id>/<logical unit id>/<file name>.

dst_filestr

Destination file name on the user system.

remove_filebool, optional

Delete the file on Exostiv Blade when True, by default False.

Returns
_type_

_description_

get_capture_state()

Returns the current capture state.

The capture state string has on or more parts:

  • The first part shows the base state.

  • A second part represents capture events.

Base states:

  • Idle : no capture is running.

  • Prefetching : data preceding the trigger is being stored.

  • Waiting for trigger : while waiting for a trigger, the data preceding the trigger is continuously refreshed.

  • Capturing : the trigger event occurred and the data past the trigger is now stored.

  • Transferring data : the sampled data is transferred from the capture memory.

  • Encoding data : the data is encoded for the wave viewer.

  • Done : the capture is done.

Events:

  • Network error : a network error occurred.

  • Capture aborted : the user aborted the capture.

  • Transfer aborted : the user aborted the transfer.

  • Encoding aborted : the user aborted the encoding.

  • Overflow : a data overflow occurred on the IP high speed link.

Returns
str or int

State on success, -1 on error.

get_dir_info(path)

Gets the directory information of the specified path. (Blade only)

Parameters
pathstr

Folder path ofr the form : HOME/<user login>/<one or more subdirectories>

Returns
_type_

_description_

get_disable_wave_encoding()

Returns whether the wave encoding is disabled.

Returns
bool or int

Disable value in success, error code otherwise.

get_exportwaves_format() → WavesExportFormat

Returns the value defined by ‘set_exportwaves_format’.

Returns
WavesExportFormat

Waves export format.

get_exportwaves_radix() → WavesExportRadix

Returns the value defined by ‘set_exportwaves_radix’.

Returns
WavesExportRadix

Waves export radix.

get_exportwaves_range()

Returns the values defined by ‘set_exportwaves_range’.

Returns
str or int

Range on success, -1 on error.

get_exportwaves_samples() → WavesExportSamples

Returns the samples to export.

Returns
WavesExportSamples

Samples to export.

get_manual_data_download()

Returns the value set by ‘set_manual_data_download’.

Returns
bool or int

Boolean enable value on success, -1 on error

get_nr_of_captures()

Returns the number of captures. Meaning, how many times a trigger event start a capture.

Returns
int

Number of captures on success, -1 on error.

get_output_equation()

Returns the output equation configuration.

Returns
OutputEquation or int

Output equation configuration (see OutputEquation class) on success, error code otherwise.

get_samples_per_capture()

Returns the number samples taken on a trigger event.

Returns
int

Number samples on success, error code otherwise.

get_stored_captures()

Returns the currently stored captures. This values ranges from 0 to the values defined by ‘set_nr_of_captures’.

Returns
int

Stored captures on success, -1 on error.

get_stored_samples()

Returns the currently stored samples within the current capture.

Returns
int

Stored samples on success, -1 on error.

get_transfer_mode() → TransferMode

Returns the IP data transfer mode.

Returns
TransferMode

Data transfer mode, burst or stream.

get_trigger_counter(trigger_type: TriggerCounterType)

Returns the trigger or qualification counter configuration.

Parameters
trigger_typeTriggerCounterType

Trigger or qualification counter.

Returns
bool, int or int

Counter enable and counter value tuple on success; error code otherwise.

get_trigger_operation(signal_name)

Returns the trigger operation and values for signal defined by argument ‘signal_name’.

Parameters
signal_namestr

Signal name.

Returns
TriggerOperation, str, str or int

Trigger operation and corresponding values tuple on success; error code otherwise.

get_trigger_position()

Returns the trigger position in one capture window.

Returns
int

Trigger position on success, -1 on error.

get_trigger_radix(signal_name)

Returns the radix for the signal used in the trigger equation.

Parameters
signal_namestr

Signal name.

Returns
TriggerRadix, TriggerRadix, or int

TriggerRadix, TriggerRadix tuple on success; error code otherwise.

get_trigger_signal_enable(signal_name)

Returns whether the signal defined by argument ‘signal_name’ is enabled for the trigger equation.

Parameters
signal_namestr

Signal name.

Returns
bool or int

True or False on success, error code otherwise.

handle_success(success)

Return the IP link state.

Returns
bool

True if the IP link is up, False otherwise.

ip_valid()

Checks whether the IP UUID matches the UUID as defined in the project file.

Returns
bool

True if the IP has the expected UUID, False otherwise.

make_probe_bus(probe_offset, bus_width, bus_name)

Make a ‘bus_width’ wide bus from probe at offset ‘probe_offset’ and use ‘bus_name’ for the newly created bus.

Parameters
probe_offsetint

Offset of the first probe.

bus_widthint

Width of the new bus.

bus_namestr

Name of the new bus.

Returns
int

0 on success, error code otherwise.

open_project(path, send_local_file: bool = True)

Loads a project file in Exostiv Client.

Parameters
pathstr

Path to a project file.

send_local_filebool, optional

Send the project file to the remote client if true, by default True

Returns
int

0 on success, error code otherwise.

ping(ping_id)

Sends an echo request to the Client application. The client replies with ‘ping_id’ on success.

Parameters
ping_idint

Arbitrary identification number.

Returns
int

0 on success, -1 on error.

reconnect_session(uuid)

Reconnect to a session. This method should only be used if the Exostiv Client has been unexpectedly disconnected from the Blade. It allows the user to reconnect to a running session. (Blade only)

Parameters
int

0 on success, error code otherwise.

Returns
int

0 on success, error code otherwise.

remove_trigger(signal_name)

Remove a trigger from the current capture unit equation.

Parameters
signal_namestr

Signal name.

Returns
int

0 on success, error code otherwise.

rename_probe(probe_offset, new_name)

Change the name for the probe at offset ‘probe_offset’.

Parameters
probe_offsetint

Probe offset.

new_namestr

New name for the probe at offset ‘probe_offset’.

Returns
int

0 on success, error code otherwise.

restore_probe(probe_offset)

Renames a single bit probe to is default name. It the offset matches a bus, the bus will first be split.

Parameters
probe_offsetint

Probe offset.

Returns
int

0 on success, error code otherwise.

save_project()

Saves the current project file.

Returns
int

0 on success, error code otherwise.

select_capture_unit(name)

Selects the capture unit as defined by argument ‘name’.

Parameters
namestr

Capture unit name.

Returns
int

0 on success, -1 on error.

select_data_group(name)

Selects the data group as defined by argument ‘name’.

Parameters
namestr

Data group name.

Returns
int

0 on success, -1 on error.

select_equation(trigger_type: TriggerType, trigger_function: TriggerFunction)

Select the trigger type and trigger function for the current capture unit.

Parameters
trigger_typeTriggerType

Trigger or Qualification.

trigger_functionTriggerFunction

AND or OR.

Returns
int

0 on success, error code otherwise.

selected_capture_unit()

Returns the name of the currently selected capture unit.

Returns
str or int

Capture unit name. -1 when not connected to a client.

selected_data_group()

Returns the name of the currently selected data group.

Returns
str or int

Data group name. -1 when not connected to a client.

selected_equation()

Selected trigger type and trigger function for the current capture unit.

Returns
TriggerType, TriggerFunction or int

Trigger type and trigger function tuple on success; error code otherwise.

set_disable_wave_encoding(disable)

This method makes it possible to disable the wave encoding is the user only needs the raw sampled data. Disabling the wave encoding speeds up the capturing process.

Parameters
disablebool

Enable or disable the wave encoding.

Returns
int

0 on success, error code otherwise.

set_exportwaves_format(export_format: WavesExportFormat)

Defines the format to be used when exporting waves.

Parameters
export_formatWavesExportFormat

Waves export format.

Returns
int

0 on success, error code otherwise.

set_exportwaves_radix(radix: WavesExportRadix)

Defines the radix to be used when exporting waves.

Parameters
radixWavesExportRadix

Waves export radix.

Returns
int

0 on success, error code otherwise.

set_exportwaves_range(export_range)

Defines the range of samples or captures to export. This method is only useful after calling ‘set_exportwaves_samples’ with argument ‘RangeOfCapture’ or ‘RangeOfSamples’.

Parameters
export_rangestr

Samples to export. Individual samples are comma separated. Ranges are dash separated.

Example: 1,6,9-17

result : Samples 1, 6 and 9 to 17 will be exported

Returns
int

0 on success, error code otherwise.

set_exportwaves_samples(export_type: WavesExportSamples)

Defines what samples to export.

Parameters
export_typeWavesExportSamples

Samples to export.

Returns
int

0 on success, error code otherwise.

set_manual_data_download(enable)

Defines whether the data is automatically downloaded from the IP at the end of a capture run (default). If manual data download is enabled, it will be up to the user to call ‘capture_download_data’ to download the data from the Probe or Blade.

Parameters
enablebool

Enable or disable the manual data download.

Returns
int

0 on success, error code otherwise.

set_nr_of_captures(nr_of_captures)

Defines the number of captures. Meaning, how many times a trigger event start a capture.

Parameters
nr_of_capturesint

Number of captures.

Returns
int

0 on success, -1 on error.

set_output_equation(equation: OutputEquation)

Defines tout equation for the output logic.

Parameters
equationOutputEquation

Configuration for the output equation.

Returns
int

0 on success, error code otherwise.

set_samples_per_capture(samples_per_capture)

Defines the number samples taken on a trigger event.

Parameters
samples_per_captureint

Number of samples per capture.

Returns
int

0 on success, error code otherwise.

set_transfer_mode(mode: TransferMode)

Defines the IP data transfer mode.

Parameters
modeTransferMode

Data transfer mode, burst or stream.

Returns
int

0 on success, error code otherwise.

set_trigger_counter(trigger_type: TriggerCounterType, enable, value=None)

Configures the trigger or qualification counter.

Parameters
trigger_typeTriggerCounterType

Trigger or qualification counter.

enablebool

Enables or disables the counter.

valueint, optional

Counter value, by default None.

Returns
int

0 on success, error code otherwise.

set_trigger_operation(signal_name, operation: TriggerOperation, value1, value2='')

Defines the trigger operation values for signal defined by argument ‘signal_name’.

Parameters
signal_namestr

Signal name.

operationTriggerOperation

Trigger operation as defined in class TriggerOperation.

value1str

A value matching the type defined by argument ‘operation’.

value2str, optional

A value matching the type defined by argument ‘operation’. ‘value2’ is only valid for range operations. By default “”.

Returns
int

0 on success, error code otherwise.

set_trigger_position(trigger_position)

Defines the trigger position in one capture window.

Parameters
trigger_positionint

Trigger position.

Returns
int

0 on success, error code otherwise.

set_trigger_radix(signal_name, radix1: TriggerRadix, radix2=TriggerRadix.Hex)

Sets the radix for the signal used in the trigger equation.

Parameters
signal_namestr

Signal name.

radix1TriggerRadix

Radix for value 1 in the trigger equation.

radix2TriggerRadix, optional

Radix for value 2 in the trigger equation, by default TriggerRadix.Hex

Returns
int

0 on success, error code otherwise.

set_trigger_signal_enable(signal_name, enable)

Enables or disables a signal in the current capture unit equation. A disabled signal is ignored and will not be part of the trigger equation.

Parameters
signal_namestr

Signal name.

enablebool

True to enable, False to disable.

Returns
int

0 on success, error code otherwise.

split_probe_bus(probe_offset)

Splits a bus into single bit probes.

Parameters
probe_offsetint

Bus offset.

Returns
int

0 on success, error code otherwise.