Skip to content

Nominal Instrument¤

Base instrument interface and background worker support.

Primary entry point: Instrument. Transport/protocols: SCPI, VISA.

logger module-attribute ¤

logger = getLogger(__name__)

Instrument ¤

Instrument(
    name: str,
    connection_config: ConnectConfig | None,
    publishers: list[Publisher] | None = None,
    background_config: BackgroundDaemonConfig | None = None,
    **kwargs,
)

Base class for all Nominal instrument interfaces.

This class provides common functionality for instrument communication, data publishing, and background worker daemon management. Subclasses should implement instrument type specific behavior.

Parameters:

  • name ¤

    (str) –

    A name to identify this instrument instance. Used in channel naming and published data.

  • connection_config ¤

    (ConnectConfig | None) –

    Connection configuration for instruments that require a communication interface (e.g., SCPI/VISA). Set to None for instruments that use vendor-specific libraries.

  • publishers ¤

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

    List of publishers to send data to when measurements or commands are executed. Defaults to None.

  • background_config ¤

    (BackgroundDaemonConfig | None, default: None ) –

    Configuration for the background worker daemon. If None, a default configuration is created. 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.

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.

open ¤

open()

Open a connection to the instrument.

This method establishes communication with the instrument if a connection configuration has been provided. If no data_handler exists (connection_config was None), this method does nothing.

close ¤

close()

Close the connection to the instrument and clean up resources.

This method stops the background worker thread, closes the instrument connection, and closes all publishers. It should be called when done using the instrument to ensure proper cleanup of resources.

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.