Skip to content

Electronic Load¤

Interface¤

electronic load instrument interface and helpers.

Defines NominalELoad and related helpers. Transport/protocols: SCPI, VISA.

Public API

NominalELoad, NominalELoadFacade

logger module-attribute ¤

logger = getLogger(__name__)

NominalELoad ¤

NominalELoad(
    name: str,
    connection_config: ConnectConfig,
    driver: ELoadDriverBase,
    publishers: list[Publisher] | None = None,
    **kwargs,
)

Bases: NominalInstrument

E-Load hardware abstraction to communicate with various models and vendor E-Loads.

Methods return Measurement and Command data types to be compatible with Nominal Instrumentation tools.

Parameters:

  • name ¤

    (str) –

    A name to identify this e-load instance. Used in channel naming and published data.

  • connection_config ¤

    (ConnectConfig) –

    Connection configuration for the e-load (SCPI/VISA).

  • driver ¤

    (ELoadDriverBase) –

    The driver instance for the specific e-load vendor/model.

  • publishers ¤

    (list[Publisher] | None, default: None ) –

    List of publishers to send data to when executing methods. Defaults to None.

  • **kwargs ¤

    –

    Optional keyword arguments used as tags throughout the life of the instrument. These tags are applied to the Measurement and Command objects and can be utilized by publishers like NominalCorePublisher as added metadata.

    Special keyword arguments: dataset_rid (str): If provided, automatically creates and adds a NominalCorePublisher with the specified dataset RID. Assumes a Nominal 'default' credential is stored on disk.

name instance-attribute ¤

name = name

data_handler instance-attribute ¤

data_handler = (
    None
    if connection_config is None
    else DataHandler(select(connection_config))
)

publishers instance-attribute ¤

publishers = publishers or []

default_tags instance-attribute ¤

default_tags: dict[str, str] = {}

background_interval property writable ¤

background_interval

Get the background worker interval setting.

Returns:

  • float –

    The current interval in seconds between background worker iterations. The worker waits this duration between executing background daemon functions.

background_enable property writable ¤

background_enable

Get the background worker enable state.

Returns:

  • bool –

    True if the background worker is enabled, False otherwise.

auto_create classmethod ¤

auto_create(
    name: str,
    resource: ConnectConfig,
    publishers: list[Publisher] | None = None,
    **kwargs,
) -> NominalELoad

Discover and create a NominalELoad instance by querying the instrument's IDN.

This factory method automatically discovers the e-load model and creates an appropriate driver instance from Nominal's list of registered eload vendors/models.

The discovery process: 1. Open a VISA session to the resource string. 2. Send '*IDN?' query. 3. Parse the returned vendor/model string. 4. Find a matching driver subclass. 5. Close the temporary session. 6. Create and return a NominalELoad instance with the appropriate driver.

Parameters:

  • name ¤
    (str) –

    A name to identify this e-load instance. Used in channel naming and published data.

  • resource ¤
    (ConnectConfig) –

    A ConnectConfig for SCPI/VISA devices.

  • publishers ¤
    (list[Publisher] | None, default: None ) –

    List of publishers to send data to when executing methods. Defaults to None.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags throughout the life of the instrument. These tags are applied to the Measurement and Command objects and can be utilized by publishers like NominalCorePublisher as added metadata.

    Special keyword arguments: dataset_rid (str): If provided, automatically creates and adds a NominalCorePublisher with the specified dataset RID. Assumes a Nominal 'default' credential is stored on disk.

Returns:

  • NominalELoad ( NominalELoad ) –

    Configured e-load instance with the appropriate driver.

Raises:

  • ValueError –

    If no matching driver is found for the IDN string.

  • TypeError –

    If resource is a string (vendor library devices require manual construction).

open ¤

open()

Establish connection to the device.

close ¤

close()

Disconnect from the device.

set_mode ¤

set_mode(mode: LoadMode, channel: int = 1, **kwargs) -> Command

Set the operation mode for the selected channel.

Select from the following operation modes: CC (Constant Current), CR (Constant Resistance), CP (Constant Power), or CV (Constant Voltage). Note that not all modes are supported by all e-load models. Check your model's documentation.

Parameters:

  • mode ¤
    (LoadMode) –

    The operation mode to set (CC, CR, CP, or CV).

  • channel ¤
    (int, default: 1 ) –

    The target channel. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Command object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Command ( Command ) –

    A Command object containing the channel name, mode value, timestamp, and tags. The command is automatically published to all configured publishers.

Raises:

  • ValueError –

    If an unsupported mode is specified for this e-load model.

set_level ¤

set_level(
    value: float,
    channel: int = 1,
    curr_limit: float | None = None,
    **kwargs,
) -> Command

Set the operation level of the selected channel.

The units depend on the current operation mode: - CC (Constant Current): amperes (A) - CV (Constant Voltage): volts (V) - CP (Constant Power): watts (W) - CR (Constant Resistance): ohms (Ω)

Parameters:

  • value ¤
    (float) –

    The operating level value in the units appropriate for the current mode.

  • channel ¤
    (int, default: 1 ) –

    The specified output channel. Defaults to 1.

  • curr_limit ¤
    (float | None, default: None ) –

    The optional current limit to set when operating mode is CV (Constant Voltage). Defaults to None.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Command object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Command ( Command ) –

    A Command object containing the channel name, level value, timestamp, and tags. The command is automatically published to all configured publishers.

Raises:

  • ValueError –

    If mode has not been set before calling this method.

short_output ¤

short_output(enable: bool, channel: int = 1, **kwargs) -> Command

Enable or disable the e-load channel short.

Warning

This action occurs IMMEDIATELY when called and will short the channel output if enabled. Use with caution.

Parameters:

  • enable ¤
    (bool) –

    True to enable the channel short, False to disable.

  • channel ¤
    (int, default: 1 ) –

    The specified output channel. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Command object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Command ( Command ) –

    A Command object containing the channel name, short enable state, timestamp, and tags. The command is automatically published to all configured publishers.

set_range ¤

set_range(value: float, channel: int = 1, **kwargs) -> Command

Set the operation range setting of the e-load.

This method sets the appropriate range based on the expected maximum operation value for the current mode.

Parameters:

  • value ¤
    (float) –

    Expected maximum operation value. The units depend on the current mode: - CC: maximum current in amperes (A) - CV: maximum voltage in volts (V) - CP: maximum power in watts (W) - CR: maximum resistance in ohms (Ω)

  • channel ¤
    (int, default: 1 ) –

    The specified output channel. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Command object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Command ( Command ) –

    A Command object containing the channel name, range value, timestamp, and tags. The command is automatically published to all configured publishers.

Raises:

  • ValueError –

    If mode has not been set before calling this method.

set_slewrate ¤

set_slewrate(
    direction: SlewRateDirection,
    rate: float,
    channel: int = 1,
    **kwargs,
) -> Command

Set the slew rate in A/μs for the assigned channel.

The slew rate controls how quickly the current can change when transitioning between levels.

Parameters:

  • direction ¤
    (SlewRateDirection) –

    The edge direction to set the slew rate (RISING or FALLING).

  • rate ¤
    (float) –

    The slew rate in amperes per microsecond (A/μs).

  • channel ¤
    (int, default: 1 ) –

    The channel to set the slew rate. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Command object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Command ( Command ) –

    A Command object containing the channel name, slew rate value, timestamp, and tags. The command is automatically published to all configured publishers.

output_enable ¤

output_enable(enable: bool, channel: int = 1, **kwargs) -> Command

Enable or disable the channel output.

Parameters:

  • enable ¤
    (bool) –

    True to enable the output, False to disable.

  • channel ¤
    (int, default: 1 ) –

    The specified output channel. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Command object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Command ( Command ) –

    A Command object containing the channel name, enable state, timestamp, and tags. The command is automatically published to all configured publishers.

get_current ¤

get_current(channel: int = 1, **kwargs) -> Measurement | None

Query the current that the e-load senses through its terminals.

Parameters:

  • channel ¤
    (int, default: 1 ) –

    The specified output channel. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Measurement object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Measurement | None –

    Measurement | None: A Measurement object containing the channel name, current value, timestamp, and tags. The measurement is automatically published to all configured publishers. Returns None if the measurement could not be obtained.

get_voltage ¤

get_voltage(channel: int = 1, **kwargs) -> Measurement | None

Query the voltage that the e-load senses is active on its terminals.

Parameters:

  • channel ¤
    (int, default: 1 ) –

    The specified output channel. Defaults to 1.

  • **kwargs ¤
    –

    Optional keyword arguments used as tags. These tags are applied to the Measurement object and can be utilized by publishers like NominalCorePublisher as added metadata.

Returns:

  • Measurement | None –

    Measurement | None: A Measurement object containing the channel name, voltage value, timestamp, and tags. The measurement is automatically published to all configured publishers. Returns None if the measurement could not be obtained.

add_publisher ¤

add_publisher(publisher: Publisher)

Add a publisher to the list of publishers for this instrument.

Publishers receive all Measurement and Command objects that are published by this instrument. Multiple publishers can be added to send data to different destinations.

Parameters:

  • publisher ¤
    (Publisher) –

    The publisher instance to add.

publish ¤

publish(data: Measurement | Command, **kwargs)

Publish a Measurement or Command to all configured publishers.

This method sends the data to all publishers that have been added to this instrument. Additional keyword arguments are passed through to each publisher's publish method.

Parameters:

  • data ¤
    (Measurement | Command) –

    The measurement or command data to publish.

  • **kwargs ¤
    –

    Optional keyword arguments passed to each publisher's publish method.

get_identity ¤

get_identity() -> str

Query the instrument's identity string.

This method sends the SCPI "*IDN?" command to retrieve the instrument's identification information, which typically includes manufacturer, model number, serial number, and firmware version.

Returns:

  • str ( str ) –

    The instrument's identity string.

Raises:

  • RuntimeError –

    If no connection is configured for this instrument (data_handler is None).

open_and_get_identity staticmethod ¤

open_and_get_identity(connection_config: ConnectConfig) -> str

Convenience method to open a connection, query identity, and close.

This static method creates a temporary instrument instance, opens a connection, queries the identity, closes the connection, and returns the identity string. Useful for instrument discovery without maintaining a long-lived connection.

Parameters:

  • connection_config ¤
    (ConnectConfig) –

    The connection configuration for the instrument.

Returns:

  • str ( str ) –

    The instrument's identity string.

Raises:

  • RuntimeError –

    If the connection cannot be established or the identity cannot be queried.

send_arbitrary_command ¤

send_arbitrary_command(command: str)

Send an arbitrary command string to the instrument.

This method allows sending custom commands directly to the instrument without going through the instrument's high-level API. Useful for accessing instrument-specific features not exposed by the standard interface.

Parameters:

  • command ¤
    (str) –

    The command string to send to the instrument.

Raises:

  • RuntimeError –

    If no connection is configured for this instrument (data_handler is None).

query_arbitrary_command ¤

query_arbitrary_command(command: str) -> str

Send an arbitrary command string and return the instrument's response.

This method sends a command and waits for a response, useful for querying instrument state or configuration. The response is returned as a string.

Parameters:

  • command ¤
    (str) –

    The query command string to send to the instrument.

Returns:

  • str ( str ) –

    The instrument's response to the query command.

Raises:

  • RuntimeError –

    If no connection is configured for this instrument (data_handler is None).

add_background_daemon_function ¤

add_background_daemon_function(method: Callable, *args, **kwargs)

Adds a function (and its arguments) to be periodically called by the background worker daemon.

There may already be functions defined and this will add to the end of that list. Call define_background_daemon to clear and define a new function if you do not want the default functions to run.

Parameters:

  • method ¤
    (Callable) –

    The method/function to be invoked in the background thread.

  • *args ¤
    –

    Positional arguments to pass to the method.

  • **kwargs ¤
    –

    Keyword arguments to pass to the method.

start ¤

start()

Start the background worker thread.

This method creates and starts a daemon thread that periodically executes all registered background daemon functions. If the thread is already running, this method does nothing. The thread will continue running until stop() is called.

stop ¤

stop()

Stop the background worker thread.

This method signals the background worker thread to stop and waits for it to complete. If the thread is not running, this method does nothing.

get_channel ¤

get_channel(
    channel_name: str,
    length: int = 1,
    wait_for_latest: bool = False,
    timeout: float = 10.0,
) -> Measurement

Get most recent Measurement data for a specific channel from the buffer.

Parameters:

  • channel_name ¤
    (str) –

    The name of the channel from which to retrieve data.

  • length ¤
    (int, default: 1 ) –

    The number of most recent samples to return.

  • wait_for_latest ¤
    (bool, default: False ) –

    Block and wait for the next channel value(s).

  • timeout ¤
    (float, default: 10.0 ) –

    Timeout in seconds when waiting for channel or values. Defaults to 10.0 seconds. Only applies when wait_for_latest=True.

Returns:

  • Measurement ( Measurement ) –

    A Measurement object containing the requested channel data and timestamps.

Raises:

  • RuntimeError –

    No background buffer exists because start() was not called.

  • ChannelNotFoundTimeoutError –

    If wait_for_latest=True and the channel does not appear within timeout.

  • ChannelValueTimeoutError –

    If wait_for_latest=True and sufficient values are not available within timeout.

define_background_daemon ¤

define_background_daemon(method: Callable, *args, **kwargs)

Clear all background daemon functions and register a single custom method.

This method clears any previously registered background daemon functions and registers a new method to be called in the background daemon loop. This is useful when you want to replace the default background functions with a custom implementation.

Parameters:

  • method ¤
    (Callable) –

    The method to call as part of the background daemon.

  • *args ¤
    –

    Positional arguments to pass to the method when it is called.

  • **kwargs ¤
    –

    Keyword arguments to pass to the method when it is called.

NominalELoadFacade ¤

NominalELoadFacade(nominal_eload: NominalELoad)

Facade class that provides drivers with access to NominalELoad configuration.

This class implements the APINominalELoad interface and allows drivers to access e-load configuration without direct access to the NominalELoad instance's internal state.

Parameters:

  • nominal_eload ¤

    (NominalELoad) –

    The NominalELoad instance to provide access to.

mode property ¤

mode: LoadMode

Get the current operation mode of the e-load.

Returns:

  • LoadMode ( LoadMode ) –

    The current operation mode (CC, CR, CP, or CV).

Raises:

Types & Configuration¤

electronic load instrument interface and helpers.

Defines LoadMode and related helpers. Public API: LoadMode, SlewRateDirection

LoadMode ¤

Bases: Enum

CC class-attribute instance-attribute ¤

CC = 'CC'

CR class-attribute instance-attribute ¤

CR = 'CR'

CP class-attribute instance-attribute ¤

CP = 'CP'

CV class-attribute instance-attribute ¤

CV = 'CV'

SlewRateDirection ¤

Bases: Enum

RISE class-attribute instance-attribute ¤

RISE = 'RISE'

FALL class-attribute instance-attribute ¤

FALL = 'FALL'

BOTH class-attribute instance-attribute ¤

BOTH = 'BOTH'

Driver Interface¤

electronic load instrument interface and helpers.

Defines ELoadDriverBase and related helpers. Transport/protocols: SCPI.

Public API

APINominalELoad, ELoadDriverBase, ELoadDriverDataHandler

logger module-attribute ¤

logger = getLogger(__name__)

APINominalELoad ¤

Bases: Protocol

API for the NominalELoad instrument type.

mode property ¤

mode: LoadMode

Get the current mode (CC, CR, CP, CV) of the E-Load.

ELoadDriverBase ¤

Bases: ABC

Abstract base class for vendor E-Load.

Each concrete provider implements sending and receiving data for its vendor/model.

hal instance-attribute ¤

hal: APINominalELoad

open ¤

open() -> None

Open connection to the device. Override in subclasses if needed.

close ¤

close() -> None

Close connection to the device. Override in subclasses if needed.

short_output abstractmethod ¤

short_output(enable: bool, channel: int)

set_mode abstractmethod ¤

set_mode(mode: LoadMode, channel: int)

set_level abstractmethod ¤

set_level(
    mode: LoadMode, value: float, channel: int, curr_limit: float | None
)

set_range abstractmethod ¤

set_range(mode: LoadMode, value: float, channel: int)

set_slewrate abstractmethod ¤

set_slewrate(direction: SlewRateDirection, rate: float, channel: int)

output_enable abstractmethod ¤

output_enable(enable: bool, channel: int)

get_current abstractmethod ¤

get_current(channel: int) -> float

get_voltage abstractmethod ¤

get_voltage(channel: int) -> float

ELoadDriverDataHandler ¤

ELoadDriverDataHandler()

Bases: ELoadDriverBase

data_handler property ¤

data_handler: DataHandler

Get the data handler, ensuring it's been set.

hal instance-attribute ¤

hal: APINominalELoad

set_data_handler ¤

set_data_handler(data_handler: DataHandler) -> None

Set the data handler for SCPI-based drivers.

Parameters:

  • data_handler ¤
    (DataHandler) –

    The DataHandler instance to use for communication

get_driver classmethod ¤

get_driver(idn: str) -> type[ELoadDriverDataHandler]

Find the appropriate driver class for a given IDN string.

Parameters:

  • idn ¤
    (str) –

    The *IDN? response string from the instrument

Returns:

Raises:

  • ValueError –

    If IDN is empty, no matching driver is found, or multiple drivers match

match_idn abstractmethod classmethod ¤

match_idn(idn: str) -> bool

Check if this driver can handle the given IDN string.

Parameters:

  • idn ¤
    (str) –

    The *IDN? response string from the instrument

Returns:

  • bool –

    True if this driver can handle the instrument, False otherwise

check_errors abstractmethod ¤

check_errors()

open ¤

open() -> None

Open connection to the device. Override in subclasses if needed.

close ¤

close() -> None

Close connection to the device. Override in subclasses if needed.

short_output abstractmethod ¤

short_output(enable: bool, channel: int)

set_mode abstractmethod ¤

set_mode(mode: LoadMode, channel: int)

set_level abstractmethod ¤

set_level(
    mode: LoadMode, value: float, channel: int, curr_limit: float | None
)

set_range abstractmethod ¤

set_range(mode: LoadMode, value: float, channel: int)

set_slewrate abstractmethod ¤

set_slewrate(direction: SlewRateDirection, rate: float, channel: int)

output_enable abstractmethod ¤

output_enable(enable: bool, channel: int)

get_current abstractmethod ¤

get_current(channel: int) -> float

get_voltage abstractmethod ¤

get_voltage(channel: int) -> float

Vendor Drivers¤

BK 85XXB¤

Bk 85XXB driver for electronic load instruments.

Implements BK85XXB and supporting helpers. Transport/protocols: SCPI.

Public API

loadmode_to_unit, BK85XXB

BK85XXB ¤

BK85XXB()

Bases: ELoadDriverDataHandler

Driver for the BK85XXB E-Load.

hal instance-attribute ¤
hal: APINominalELoad
data_handler property ¤
data_handler: DataHandler

Get the data handler, ensuring it's been set.

match_idn classmethod ¤
match_idn(idn: str) -> bool

Check if this driver can handle the given IDN string.

open ¤
open() -> None
short_output ¤
short_output(enable: bool, channel: int) -> None
set_mode ¤
set_mode(mode: LoadMode, channel: int) -> None
set_level ¤
set_level(
    mode: LoadMode, value: float, channel: int, curr_limit: float | None
) -> None
set_range ¤
set_range(mode: LoadMode, value: float, channel: int) -> None
set_slewrate ¤
set_slewrate(
    direction: SlewRateDirection, rate: float, channel: int
) -> None
output_enable ¤
output_enable(enable: bool, channel: int) -> None
get_current ¤
get_current(channel: int) -> float
get_voltage ¤
get_voltage(channel: int) -> float
check_errors ¤
check_errors()
close ¤
close() -> None

Close connection to the device. Override in subclasses if needed.

set_data_handler ¤
set_data_handler(data_handler: DataHandler) -> None

Set the data handler for SCPI-based drivers.

Parameters:

  • data_handler ¤
    (DataHandler) –

    The DataHandler instance to use for communication

get_driver classmethod ¤
get_driver(idn: str) -> type[ELoadDriverDataHandler]

Find the appropriate driver class for a given IDN string.

Parameters:

  • idn ¤
    (str) –

    The *IDN? response string from the instrument

Returns:

Raises:

  • ValueError –

    If IDN is empty, no matching driver is found, or multiple drivers match

loadmode_to_unit ¤

loadmode_to_unit(mode: LoadMode) -> str