qmi.utils.adwin_manager

Manage access to programs and data on the ADwin.

Classes

AdwinManager(adwin, program_library, ...)

Provide convenient access to ADwin processes.

AdwinProcess(adwin, name, program_info)

Access a specific process running on a specific ADwin.

AdwinProgramLibrary(program_dir, config_dir)

Manage a collection of ADwin programs.

CfgAdwinProgram(**kwargs)

Configuration for a specific Adwin program.

ProgramInfo(file, slot, trigger, priority, ...)

Information about an ADwin program.
class qmi.utils.adwin_manager.CfgAdwinProgram(**kwargs: Any)

Configuration for a specific Adwin program.

Parameters:

  • file – File name of the top-level “.bas” file without the “.bas” extension. This file name is interpreted relative to the Adwin program directory.

  • slot – Process (“slot”) number in the ADwin (range 1 to 10). Not the same as physical encasing slots.

  • trigger – Event trigger source, either “timer” or “external”.

  • priority – Process priority, either an integer between -10 and +10 for a low priority process, or 1000 for a high priority process.

  • parse_parameters – True to discover parameters by parsing the ADbasic source code.

  • par – Dictionary mapping parameter name to global Par_nn index.

  • fpar – Dictionary mapping parameter name to global FPar_nn index.

  • data – Dictionary mapping array name to global Data_nnn index.

  • par_array – Dictionary mapping parameter name to list [nnn, k] referring to array element Data_nnn[k].

class qmi.utils.adwin_manager.ProgramInfo(file: str, slot: int, trigger: str, priority: int, param_info: ParameterInfo)

Information about an ADwin program.

file

Path name to the top-level “.bas” file without the “.bas” extension.

Type:

str

slot

Process slot number in the ADwin (range 1 to 10). Not the same as physical encasing slots.

Type:

int

trigger

Event trigger source, either “timer” or “external”.

Type:

str

priority

Process priority, either an integer between -10 and +10 for a low priority process, or 1000 for a high priority process.

Type:

int

parameters

Information about parameters and data arrays in the ADbasic program.

file: str

Alias for field number 0

slot: int

Alias for field number 1

trigger: str

Alias for field number 2

priority: int

Alias for field number 3

param_info: ParameterInfo

Alias for field number 4

classmethod from_config(config: CfgAdwinProgram, program_dir: str) → ProgramInfo

Create a ProgramInfo from a CfgAdwinProgram instance.

Parameters:

  • config – Adwin program configuration.

  • program_dir – directory where adwin program files are located.

Returns:

Instance of ProgramInfo.

Raises:
classmethod from_config_file(config_file: str, program_dir: str) → ProgramInfo

Create a ProgramInfo from a program configurations file.

Parameters:

  • config_file – A configuration file with Adwin program configuration(s).

  • program_dir – directory where adwin program files are located.

Returns:

Instance of ProgramInfo.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class qmi.utils.adwin_manager.AdwinProgramLibrary(program_dir: str, config_dir: str, processor_type: str = 'T12', hardware_type: str = 'PII')

Manage a collection of ADwin programs.

list_programs() → list[str]

Return a list of available programs.

get_program_info(program_name: str) → ProgramInfo

Return information about the specified program.

This function may read a program-specific configuration file or parse the ADbasic source code to obtain information about the parameters and data arrays used by this program.

Parameters:

program_name – Unique name of the program, used to identify this program within the ADwin configuration data.

Returns:

Information about the specified program.

Raises:

  • KeyError – If the specified program name is unknown.

  • QMI_ConfigurationException – If an error occurs while reading parameter configuration data.

  • ParseException – If an error occurs while parsing the ADbasic source code.

compile(program_name: str) → None

Compile the specified program with the ADbasic compiler.

Parameters:

program_name – Unique name of the program.

Raises:

  • KeyError – If the specified program name is unknown.

  • AdbasicCompilerException – If an error occurs while compiling the program.

class qmi.utils.adwin_manager.AdwinProcess(adwin: Adwin_Base, name: str, program_info: ProgramInfo)

Access a specific process running on a specific ADwin.

An instance of this class represents a specific process on a specific ADwin instrument. The process may be in one of several states: running, loaded but not yet running, or not yet loaded.

If the process is loaded (and possibly running), data may be transferred from Python to the ADwin process and vice versa.

Global parameters and data arrays are accessed by name. These names are mapped to Par_nn, FPar_nn and Data_nn indices by lookup in a name table. This table is either specified explicitly as part of the ADwin configuration, or derived from parsing the ADbasic code.

load() → None

Load the Adwin process but do not start it yet.

If a process is already running in the same process slot number, that process will be stopped.

start() → None

Start running the Adwin process.

The process must already have been loaded by calling the load() method. The process must not already be running.

This function will not initialize or modify any parameters before starting the process.

Raises:

QMI_InstrumentException – If the process is already running.

start_with_params(**kwargs: Any) → None

Send parameter values to the Adwin, then start running the Adwin process.

The process must already have been loaded by calling the load() method. The process must not already be running.

Parameters for the Adwin process may be specified as keyword parameters to this function. These parameters will be sent to the Adwin prior to starting the process.

Notes

Parameter name lookup is performed case-insensitive.

Raises:

QMI_InstrumentException – If the process is already running.

stop() → None

Stop running the Adwin process.

is_running() → bool

Return True if the Adwin process is currently running.

It is assumed that the process is already loaded. This function only checks whether any process is running in the specified slot number. It can not guarantee that the running process matches the expected program.

wait_for_process(timeout: float) → None

Wait until the Adwin process has stopped.

Parameters:

timeout – Maximum time to wait (seconds).

Raises:

QMI_TimeoutException – If the process does not stop before timeout occurs.

get_par(par_name: str) → int | float

Return the current value of the specified parameter.

Notes

Parameter name lookup is performed case-insensitive.

Parameters:

par_name – Parameter name.

Returns:

Value of the parameter.

set_par(par_name: str, value: int | float) → None

Change the value of the specified parameter.

Notes

Parameter name lookup is performed case-insensitive.

Parameters:

  • par_name – Parameter name.

  • value – New value to write to the parameter.

get_par_multiple(params: list[str]) → dict[str, int | float]

Fetch multiple parameter values from the Adwin.

Notes

Parameter name lookup is performed case-insensitive.

set_par_multiple(params: dict[str, int | float]) → None

Send multiple parameter values to the Adwin.

Notes

Parameter name lookup is performed case-insensitive.

get_data_length(data_name: str) → int

Return the length of the specified global Data array.

Notes

Data name lookup is performed case-insensitive.

Parameters:

data_name – Name of the data array.

Returns:

Number of elements in the array.

get_data(data_name: str, first_index: int, count: int) → ndarray

Read values from a global DATA array.

Notes

Data name lookup is performed case-insensitive.

Parameters:

  • data_name – Name of the data array.

  • first_index – First index into the data array (>= 1).

  • count – Number of elements to read from the data array.

Returns:

1D Numpy array with data values.

get_full_data(data_name: str) → ndarray

Read all elements from a global Data array.

Notes

Data name lookup is performed case-insensitive.

Parameters:

data_name – Name of the data array.

Returns:

1D Numpy array with data values.

set_data(data_name: str, first_index: int, value: ndarray | list[int] | list[float]) → None

Write values to a global Data array.

Notes

Data name lookup is performed case-insensitive.

Parameters:

  • data_name – Name of the data array.

  • first_index – First index into the data array (>= 1).

  • value – List of values to write to the data array.

get_fifo_filled(data_name: str) → int

Return the number of values waiting in the FIFO.

Notes

Data name lookup is performed case-insensitive.

Parameters:

data_name – Name of the data array (to look up in the Adwin configuration).

Returns:

Number of FIFO entries currently in use.

get_fifo_room(data_name: str) → int

Return the number of values that can be added to the FIFO without overflowing it.

Notes

Data name lookup is performed case-insensitive.

Parameters:

data_name – Name of the FIFO data array.

Returns:

Number of empty FIFO entries available.

read_fifo(data_name: str, count: int) → ndarray

Read data from a global FIFO variable.

Notes

Data name lookup is performed case-insensitive.

Parameters:

  • data_name – Name of the FIFO data array.

  • count – Number of values to read from the FIFO.

Returns:

1D Numpy array containing the FIFO elements.

write_fifo(data_name: str, value: ndarray | list[int] | list[float]) → None

Write data to a global FIFO variable.

Notes

Data name lookup is performed case-insensitive.

Parameters:

  • data_name – Name of the FIFO data array.

  • value – Array of values to write to the FIFO.

class qmi.utils.adwin_manager.AdwinManager(adwin: Adwin_Base, program_library: AdwinProgramLibrary, auto_load_programs: list[str])

Provide convenient access to ADwin processes.

An instance of this class manages the processes running on a specific ADwin instrument.

get_adwin() → Adwin_Base

Return the Adwin instrument driver used by this manager.

get_program_library() → AdwinProgramLibrary

Return the Adwin program library used by this manager.

reboot() → None

Reboot the Adwin system, clear data and restart programs.

This function must be called after power-on, before communication with the Adwin is possible. This function may be called again to perform a full reset.

This function boots the Adwin, removes all processes and data. It then loads the default processes as specified in the Adwin configuration.

list_programs() → list[str]

Return a list of available programs.

get_process(program_name: str) → AdwinProcess

Get an AdwinProcess instance for the specified program.