The SCPI Client

The primary entry point from this library is the ScpiClient class.

class absscpi.ScpiClient(lib: str = 'absscpi')

Client for communicating with the ABS with SCPI.

This class supports UDP, TCP, RS-485, and UDP multicast. When using serial or multicast, it can broadcast messages to all units on the bus.

Typical usage example:

with ScpiClient() as client:
    client.open_udp("192.168.1.100")
    client.set_cell_voltage(0, 2.3)
    client.enable_cell(0, True)
    # give the cell time to settle
    time.sleep(0.005)
    print(f"Cell 1 measured voltage: {client.measure_cell_voltage(0)}")

To re-open the connection with the same or a different communication layer, you can simply call the corresponding open_*() method at any time.

Parameters:

lib (str) – Name of or path to the ABS SCPI DLL. This parameter is optional. If the DLL is in a discoverable location such as C:/Windows/System32 or /usr/lib, or if it was installed to the default path by the Windows MSI installer, it will be found automatically. If it is not automatically found, pass the path to the file to this function.

Raises:

OSError – An error occurred while finding or loading the low-level library.

init()

Initialize the client handle.

Warning

Should not be called directly! Use a “with” block instead:

with ScpiClient() as client:
    ...

Raises:

ScpiClientError – An error occurred during initialization.

cleanup()

Cleanup the client handle.

Warning

Should not be called directly! Use a “with” block instead:

with ScpiClient() as client:
    ...

open_udp(target_ip: str, interface_ip: str | None = None)

Open a UDP connection to the ABS.

Parameters:

• target_ip (str) – Target device IP address.

• interface_ip (str | None) – If present, determines the IP address of the local interface to bind the socket to. When not provided, any local address may be bound.

Raises:

ScpiClientError – An error occurred while opening the socket.

open_tcp(target_ip: str)

Open a TCP connection to the ABS.

Parameters:

target_ip (str) – Target device IP address.

Raises:

ScpiClientError – An error occurred while attempting to connect.

open_serial(port: str, device_id: int)

Open a serial connection to the device.

Parameters:

• port (str) – Serial port, such as “COM1” or “/dev/ttyS1.”

• device_id (int) – Device’s serial ID, 0-31, or 32+ to address all units on the bus.

Raises:

ScpiClientError – An error occurred while opening the port.

open_udp_multicast(interface_ip: str)

Open a UDP multicast socket for broadcasting to many ABSes.

Parameters:

interface_ip (str) – IP address of the local NIC to bind to.

Raises:

ScpiClientError – An error occurred while opening the socket.

set_target_device_id(device_id: int)

Set the target device ID for communications.

Only applies to RS-485 connections.

Parameters:

device_id (int) – Target device ID, 0-31, or 32+ to broadcast to all units on the bus.

Raises:

ScpiClientError – An error occurred while setting the ID.

get_target_device_id() → int

Get the target device ID for communications.

Only relevant for RS-485 connections.

Returns:

The target device’s ID.

Raises:

ScpiClientError – An error occurred while getting the ID.

Return type:

int

get_device_info() → AbsDeviceInfo

Query basic device information from the device.

Returns:

The device information.

Raises:

ScpiClientError – An error occurred while opening the port.

Return type:

AbsDeviceInfo

get_device_id() → int

Query the device’s serial ID.

Returns:

The device’s ID.

Raises:

ScpiClientError – An error occurred querying the device.

Return type:

int

get_ip_address() → AbsEthernetConfig

Query the device’s IP address and subnet mask.

Returns:

The Ethernet configuration of the device.

Raises:

ScpiClientError – An error occurred querying the device.

Return type:

AbsEthernetConfig

set_ip_address(ip: str, netmask: str)

Set the device’s IP address and subnet mask.

For TCP and UDP connections, you must close and reopen the connection. This can be achieved by simply calling the corresponding open_*() method again.

Parameters:

• ip (str) – Desired IPv4 address.

• netmask (str) – Desired IPv4 subnet mask.

Raises:

ScpiClientError – An error occurred sending the command.

get_calibration_date() → str

Query the device’s calibration date.

Returns:

Device’s calibration date.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

str

get_error_count() → int

Query the number of errors in the device’s error queue.

Returns:

Number of errors in the error queue.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

int

get_next_error() → tuple[int, str] | None

Query the next error from the device’s error queue.

Returns:

A tuple containing the returned error code and message or None if the error code was 0 (no error).

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

tuple[int, str] | None

clear_errors()

Clear the device’s error queue.

Raises:

ScpiClientError – An error occurred while sending the command.

get_alarms() → int

Query the alarms raised on the device.

Returns:

The alarms bitmask.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

int

get_interlock_state() → bool

Query the system interlock state. When in interlock, the system will be put into its PoR state and cannot be controlled until the interlock is lifted.

Returns:

The interlock state.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

bool

assert_soft_interlock()

Assert the software interlock (a recoverable alarm).

The interlock may be cleared using the clear_recoverable_alarms() method.

Raises:

ScpiClientError – An error occurred while sending the command.

clear_recoverable_alarms()

Clear any recoverable alarms raised on the unit (including software interlock).

Raises:

ScpiClientError – An error occurred while sending the command.

reboot()

Reboot the device, resetting it to its POR state.

Rebooting takes about 8-10 seconds. If using TCP, you’ll need to re-open the connection after the device has rebooted.

Raises:

ScpiClientError – An error occurred while sending the command.

enable_cell(cell: int, en: bool)

Enable or disable a single cell.

Parameters:

• cell (int) – Target cell index, 0-7.

• en (bool) – Whether to enable the cell.

Raises:

ScpiClientError – An error occurred while enabling the cell.

enable_all_cells(en: list[bool])

Enable or disable many cells.

Parameters:

en (list[bool]) – List of cell enable states. Must not be longer than the total cell count.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_enabled(cell: int) → bool

Query the enable state of a single cell.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

Whether the cell is enabled.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

bool

get_all_cells_enabled() → list[bool]

Query the enable state of all cells.

Returns:

List of cell enable states, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[bool]

set_cell_voltage(cell: int, voltage: float)

Set a single cell’s target voltage.

Parameters:

• cell (int) – Target cell index, 0-7.

• voltage (float) – Cell voltage.

Raises:

ScpiClientError – An error occurred while sending the command.

set_all_cell_voltages(voltages: list[float])

Set all cells’ voltages.

Parameters:

voltages (list[float]) – Array of cell voltages. Must not be empty or longer than the total cell count.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_voltage_target(cell: int) → float

Query a single cell’s target voltage.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

The cell’s target voltage.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

get_all_cell_voltage_targets() → list[float]

Query all cells’ target voltages.

Returns:

An array of voltages, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

set_cell_sourcing(cell: int, limit: float)

Set a single cell’s current sourcing limit.

Parameters:

• cell (int) – Target cell index, 0-7.

• limit (float) – Sourcing limit.

Raises:

ScpiClientError – An error occurred while sending the command.

set_all_cell_sourcing(limits: list[float])

Set all cells’ current sourcing limits.

Parameters:

limits (list[float]) – Array of current limits. Must not be empty or longer than the total cell count.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_sourcing_limit(cell: int) → float

Query a single cell’s current sourcing limit.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

The cell’s current sourcing limit.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

get_all_cell_sourcing_limits() → list[float]

Query all cells’ current sourcing limits.

Returns:

An array of current sourcing limits, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

set_cell_sinking(cell: int, limit: float)

Set a single cell’s current sinking limit.

Parameters:

• cell (int) – Target cell index, 0-7.

• limit (float) – Sinking limit.

Raises:

ScpiClientError – An error occurred while sending the command.

set_all_cell_sinking(limits: list[float])

Set all cells’ current sinking limits.

Parameters:

limits (list[float]) – Array of current limits. Must not be empty or longer than the total cell count.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_sinking_limit(cell: int) → float

Query a single cell’s current sinking limit.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

The cell’s current sinking limit.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

get_all_cell_sinking_limits() → list[float]

Query all cells’ current sinking limits.

Returns:

An array of current sinking limits, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

set_cell_fault(cell: int, fault: AbsCellFault)

Set a single cell’s faulting state.

Parameters:

• cell (int) – Target cell index, 0-7.

• fault (AbsCellFault) – Fault state.

Raises:

ScpiClientError – An error occurred while sending the command.

set_all_cell_faults(faults: list[AbsCellFault])

Set all cells’ faulting states.

Parameters:

faults (list[AbsCellFault]) – Array of fault states. Must not be empty or longer than the total cell count.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_fault(cell: int) → AbsCellFault

Query a single cell’s faulting state.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

The cell’s faulting state.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

AbsCellFault

get_all_cell_faults() → list[AbsCellFault]

Query all cells’ faulting states.

Returns:

An array of faulting states, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[AbsCellFault]

set_cell_sense_range(cell: int, range_: AbsCellSenseRange)

Set a single cell’s current sense range.

For most applications, changing this setting manually is unnecessary. By default, the cell will choose the appropriate sense range based on its sourcing and sinking current limits.

Parameters:

• cell (int) – Target cell index, 0-7.

• range – Sense range.

• range_ (AbsCellSenseRange)

Raises:

ScpiClientError – An error occurred while sending the command.

set_all_cell_sense_ranges(ranges: list[AbsCellSenseRange])

Set all cells’ current sense ranges.

For most applications, changing this setting manually is unnecessary. By default, the cells will choose the appropriate sense range based on their sourcing and sinking current limits.

Parameters:

ranges (list[AbsCellSenseRange]) – Array of sense ranges. Must not be empty or longer than the total cell count.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_sense_range(cell: int) → AbsCellSenseRange

Query a single cell’s current sense range.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

The cell’s current sense range.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

AbsCellSenseRange

get_all_cell_sense_ranges() → list[AbsCellSenseRange]

Query all cells’ current sense ranges.

Returns:

An array of sense ranges, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[AbsCellSenseRange]

enable_cell_noise_filter(en: bool)

Enable or disable the cell 50/60Hz noise filter.

This mode filters 50/60Hz noise and increases cell measurement accuracy, but decreases the cell control rate to 10Hz.

Parameters:

en (bool) – Desired filter state.

Raises:

ScpiClientError – An error occurred while sending the command.

get_cell_noise_filter_enabled() → bool

Query the enable state of the cell 50/60Hz noise filter.

Returns:

The state of the noise filter.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

bool

measure_cell_voltage(cell: int) → float

Measure a single cell’s voltage.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

Measured cell voltage.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

measure_all_cell_voltages() → list[float]

Measure all cell voltages.

Returns:

Array of voltages, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

measure_cell_current(cell: int) → float

Measure a single cell’s current.

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

Measured cell current.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

measure_all_cell_currents() → list[float]

Measure all cell currents.

Returns:

Array of currents, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

get_cell_operating_mode(cell: int) → AbsCellMode

Query a single cell’s operating mode (constant voltage or current limited).

Parameters:

cell (int) – Target cell index, 0-7.

Returns:

The cell’s operating mode.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

AbsCellMode

get_all_cell_operating_modes() → list[AbsCellMode]

Query all cells’ operating modes (constant voltage or current limited).

Returns:

An array of cell operating modes, one per cell.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[AbsCellMode]

set_analog_output(channel: int, voltage: float)

Set a single analog output voltage.

Parameters:

• channel (int) – Target channel index, 0-7.

• voltage (float) – Target voltage.

Raises:

ScpiClientError – An error occurred while executing the command.

set_all_analog_outputs(voltages: list[float])

Set all analog output voltages.

Parameters:

voltages (list[float]) – An array of voltages, one per channel. Must not be empty or longer than the total channel count.

Raises:

ScpiClientError – An error occurred while executing the command.

get_analog_output(channel: int) → float

Query an analog output’s set point.

Parameters:

channel (int) – Target channel index, 0-7.

Returns:

The analog output’s voltage.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

get_all_analog_outputs() → list[float]

Query all analog output voltages.

Returns:

An array of voltages, one per channel.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

set_digital_output(channel: int, level: bool)

Set a single digital output.

Parameters:

• channel (int) – Target channel index, 0-3.

• level (bool) – Desired output level.

Raises:

ScpiClientError – An error occurred while sending the command.

set_all_digital_outputs(levels: list[bool])

Set all digital outputs.

Parameters:

levels (list[bool]) – An array of output levels, one per channel. Must not be longer than the total channel count.

Raises:

ScpiClientError – An error occurred while executing the query.

get_digital_output(channel: int) → bool

Query the state of a single digital output.

Parameters:

channel (int) – Target channel index, 0-3.

Returns:

The state of the digital output.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

bool

get_all_digital_outputs() → list[bool]

Query the states of all digital outputs.

Returns:

An array of states, one per output.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[bool]

measure_analog_input(channel: int) → float

Measure a single analog input.

Parameters:

channel (int) – Target channel index, 0-7.

Returns:

Measured voltage.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

measure_all_analog_inputs() → list[float]

Measure all analog inputs.

Returns:

An array of voltages, one per channel.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

measure_digital_input(channel: int) → bool

Measure a single digital input.

Parameters:

channel (int) – Target channel index, 0-3.

Returns:

The state of the digital input.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

bool

measure_all_digital_inputs() → list[bool]

Measure all digital inputs.

Returns:

An array of states, one per input.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[bool]

get_model_status() → AbsModelStatus

Query the model status bits.

Returns:

Model status.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

AbsModelStatus

load_model()

Load the model configuration on the device.

Raises:

ScpiClientError – An error occurred while sending the command.

start_model()

Start modeling.

Raises:

ScpiClientError – An error occurred while sending the command.

stop_model()

Stop modeling.

Raises:

ScpiClientError – An error occurred while sending the command.

unload_model()

Unload the model configuration.

Raises:

ScpiClientError – An error occurred while sending the command.

get_model_info() → AbsModelInfo

Query information about the model.

Returns:

Model information.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

AbsModelInfo

set_global_model_input(index: int, value: float)

Set a single global model input.

This function is particularly useful with multicast to address multiple units.

Parameters:

• index (int) – The input index, 0-7.

• value (float) – The input value.

Raises:

ScpiClientError – An error occurred while executing the command.

set_all_global_model_inputs(values: list[float])

Set all global model inputs.

This function is particularly useful with multicast to address multiple units.

Parameters:

values (list[float]) – An array of values, one per input. Must not be longer than the total input count.

Raises:

ScpiClientError – An error occurred while executing the command.

get_global_model_input(index: int) → float

Query a single global model input.

Parameters:

index (int) – The input index, 0-7.

Returns:

The value of the input.

Raises:

ScpiClientError – An error occurred while executing the command.

Return type:

float

get_all_global_model_inputs() → list[float]

Query all global model inputs.

Returns:

A list of values, one per input.

Raises:

ScpiClientError – An error occurred while executing the command.

Return type:

list[float]

set_local_model_input(index: int, value: float)

Set a single local model input.

Parameters:

• index (int) – The input index, 0-7.

• value (float) – The input value.

Raises:

ScpiClientError – An error occurred while executing the command.

set_all_local_model_inputs(values: list[float])

Set all local model inputs.

Parameters:

values (list[float]) – An array of values, one per input. Must not be longer than the total input count.

Raises:

ScpiClientError – An error occurred while executing the command.

get_local_model_input(index: int) → float

Query a single local model input.

Parameters:

index (int) – The input index, 0-7.

Returns:

The value of the input.

Raises:

ScpiClientError – An error occurred while executing the command.

Return type:

float

get_all_local_model_inputs() → list[float]

Query all local model inputs.

Returns:

A list of values, one per input.

Raises:

ScpiClientError – An error occurred while executing the command.

Return type:

list[float]

get_model_output(index: int) → float

Query a single model output.

Parameters:

index (int) – Output index, 0-35.

Returns:

The model output.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

float

get_all_model_outputs() → list[float]

Query all model outputs.

Returns:

A list of all model outputs.

Raises:

ScpiClientError – An error occurred while executing the query.

Return type:

list[float]

multicast_discovery(interface_ip: str) → list[AbsEthernetDiscoveryResult]

Use UDP multicast to discover ABSes on the network.

This function does not require the ScpiClient to be initialized or connected.

Parameters:

interface_ip (str) – IP address of the local NIC to bind to.

Returns:

List of discovered devices.

Raises:

ScpiClientError – An error occurred during discovery.

Return type:

list[AbsEthernetDiscoveryResult]

serial_discovery(port: str, first_id: int = 0, last_id: int = 31) → list[AbsSerialDiscoveryResult]

Use RS-485 to discover ABSes on the bus.

This function requires that the ScpiClient not be connected over serial! This will interfere with opening the serial port.

Parameters:

• port (str) – Serial port to use, such as COM1 or /dev/ttyS0.

• first_id (int) – First serial ID to check, 0-31.

• last_id (int) – Last serial ID to check (inclusive), 0-31. Must not be less than first_id.

Returns:

List of discovered devices.

Raises:

ScpiClientError – An error occurred during discovery.

Return type:

list[AbsSerialDiscoveryResult]