nspyre.instrument

Submodules

Package Contents

Classes

InstrumentGateway

Create a connection to an InstrumentServer and access it's devices.

InstrumentGatewayDevice

Wrapper for a device residing in an InstrumentGateway.

InstrumentManager

For consolidating connections to multiple instrument gateways.

InstrumentManagerDevice

Wrapper for a device residing in an InstrumentManager.

InstrumentServer

RPyC service that loads devices and exposes them to the client.
class nspyre.instrument.InstrumentGateway(addr='localhost', port=INSTRUMENT_SERVER_DEFAULT_PORT, conn_timeout=0.0, sync_timeout=RPYC_SYNC_TIMEOUT)

Create a connection to an InstrumentServer and access it’s devices. When accessing a device through the gateway using gateway.my_device notation, an InstrumentGatewayDevice is returned.

Usage Example:

from nspyre import InstrumentGateway

with InstrumentGateway() as gw:
    # d is an InstrumentGatewayDevice object
    d = gw.dev1
    # run the set_something() method of dev1
    d.set_something(5)
    # run the get_something() method of dev1 and print its return value
    print(d.get_something())
Parameters:

  • addr (str) – Network address of the InstrumentServer.

  • port (int) – Port number of the InstrumentServer.

  • conn_timeout (float) – Lower bound on the time to wait for the connection to be established.

  • sync_timeout (float) – Time to wait for requests / function calls to finish.

Raises:

InstrumentGatewayError – Connection to the InstrumentServer failed.

connect()

Attempt connection to an InstrumentServer.

Raises:

InstrumentGatewayError – Connection to the InstrumentServer failed.

is_connected()

Return whether the gateway is connected.

Return type:

bool

disconnect()

Disconnect from the InstrumentServer.

reconnect()

Disconnect then connect to the InstrumentServer again.

Raises:

InstrumentGatewayError – Connection to the InstrumentServer failed.

class nspyre.instrument.InstrumentGatewayDevice(name, gateway)

Wrapper for a device residing in an InstrumentGateway. When we access an attribute of a device from an InstrumentGateway, it will return an rpyc netref object. This creates a problem when the gateway disconnects from the instrument server, then later reconnects. If we have an rpyc netref that pointed to a device attribute, it will be stale because it was linked to the original gateway. However, if we instead pass around this InstrumentGatewayDevice, we can always re-access the gateway device whenever we want to access an attribute of the device. This way, if the gateway disconnects then reconnects, we will always be accessing the attributes of the newly connected gateway, rather than a stale netref.

Accessing the “device” attribute will return (an rpyc netref to) the device object. Attributes of the device can be accessed directly from this object. E.g.:

from nspyre import InstrumentGateway

with InstrumentGateway() as gw:
    # let's assume "dev1" was created on the instrument server as an
    # instance of "MyDriver"

    # d is an InstrumentGatewayDevice object
    d = gw.dev1
    # run the get_something() method of dev1 and print its return value
    print(d.get_something())
    # does the same thing
    print(d.device.get_something())

    print(isinstance(gw.dev1, MyDriver)) # False
    print(isinstance(gw.dev1, InstrumentGatewayDevice)) # True
    print(isinstance(gw.dev1.device, MyDriver)) # True
Parameters:
exception nspyre.instrument.InstrumentGatewayError(*args, **kwargs)

Raised for failures related to the InstrumentGateway.

Parameters:

  • args – Arguments to pass to super class Exception().

  • kwargs – Keyword arguments to pass to super class Exception().

class nspyre.instrument.InstrumentManager(*register_gateway_args, register_gateway=True, auto_device_discovery=True, **register_gateway_kwargs)

For consolidating connections to multiple instrument gateways. If only connecting to a single InstrumentGateway, you can simply pass the arguments and keyword arguments that you’d normally pass to the gateway here. The InstrumentManager returns an InstrumentManagerDevice when a device attribute is accessed, e.g.:

from nspyre import InstrumentManager

with InstrumentManager() as mgr:
    # let's assume "dev1" was created on the instrument server as an
    # instance of "MyDriver"

    # d is an InstrumentManagerDevice object
    d = mgr.dev1
    # run the get_something() method of dev1 and print its return value
    print(d.get_something())
    print(isinstance(mgr.dev1, MyDriver)) # False
    print(isinstance(mgr.dev1, InstrumentManagerDevice)) # True
Parameters:

  • register_gateway_args – See arguments for register_gateway().

  • register_gateway (bool) – if True, call register_gateway().

  • auto_device_discovery (bool) – if True, when an attribute of the manager is accessed, but the device hasn’t been registered yet with the manager using register_device(), the device will be automatically registered.

  • register_gateway_kwargs – See keyword arguments for register_gateway().

register_gateway(*gateway_args, default_exclude=False, exclude=None, name_mapping=None, **gateway_kwargs)

Create and connect to an ~nspyre.instrument.gateway.InstrumentGateway, associate it with this InstrumentManager, and add all of its devices to this InstrumentManager.

Parameters:
register_device(dev, name=None)

Add a device to the InstrumentManager.

Parameters:
disconnect()

Disconnect from all InstrumentGateway.

class nspyre.instrument.InstrumentManagerDevice(name, manager)

Wrapper for a device residing in an InstrumentManager. Performs similar a function as an InstrumentGatewayDevice. See those docs for details.

Parameters:
class nspyre.instrument.InstrumentServer(port=INSTRUMENT_SERVER_DEFAULT_PORT, sync_timeout=RPYC_SYNC_TIMEOUT)

RPyC service that loads devices and exposes them to the client.

The RPyC service starts a new thread running an RPyC server. Clients may connect and access devices or command the server to add, remove, or restart devices (through the InstrumentGateway).

Parameters:

  • port (int) – Port number to use for the RPyC server.

  • sync_timeout (float) – Time to wait for requests / function calls to finish.

add(name, class_path, class_name, args=None, kwargs=None, import_or_file='file', local_args=False)

Create an instance of the specified class and add it to the instrument server.

Parameters:

  • name (str) – Alias for the device.

  • class_path (str) – If import_or_file is 'file', path to the file on the filesystem containing the class, e.g. '~/drivers/rohde_schwarz/hmp4040.py'. If import_or_file is 'import', python module containing the class, e.g. 'nspyre_drivers.rohde_schwarz.hmp4040.hmp4040'.

  • class_name (str) – Name of the class to create an instance of, e.g. 'HMP4040'.

  • args (Optional[list]) – Arguments to pass to class_name.__init__.

  • kwargs (Optional[Dict]) – Keyword arguments to pass to class_name.__init__..

  • import_or_file (str) – 'file' for creating the device object from a file on the filesystem, 'import' for creating the device object from a python module.

  • local_args (bool) – If True, all arguments to this method are assumed to be local variables not passed through an InstrumentGateway. In this case, the arguments will be taken as-is. If False, all arguments will be retrieved using rpyc.utils.classic.obtain in order to ensure they are not netrefs.

Raises:
remove(name)

Remove a device from the instrument server.

Parameters:

name (str) – Alias for the device.

Raises:

InstrumentServerError – Deleting the device failed.

restart(name)

Restart the specified device by deleting it and creating a new instance.

Parameters:

name (str) – Alias for the device.

Raises:

InstrumentServerError – Deleting the device failed.

restart_all()

Restart all devices on the server.

Raises:

InstrumentServerError – Deleting a device failed.

start()

Start the RPyC server.

Raises:

InstrumentServerError – The server was already running.

stop()

Stop the RPyC server.

Raises:

InstrumentServerError – The server wasn’t running.

devs()

Return all of the devices on the InstrumentSever.

Returns:

The device names as keys and device objects as values.

Return type:

dict

on_connect(conn)

Called when a client connects to the RPyC server.

Parameters:

conn (rpyc.core.protocol.Connection) –

on_disconnect(conn)

Called when a client disconnects from the RPyC server.

Parameters:

conn (rpyc.core.protocol.Connection) –

exception nspyre.instrument.InstrumentServerDeviceExistsError(*args, **kwargs)

Raised if attempting to add a device that already exists to the InstrumentServer.

Parameters:

  • args – Arguments to pass to super class Exception().

  • kwargs – Keyword arguments to pass to super class Exception().

exception nspyre.instrument.InstrumentServerError(*args, **kwargs)

Raised for failures related to the InstrumentServer.

Parameters:

  • args – Arguments to pass to super class Exception().

  • kwargs – Keyword arguments to pass to super class Exception().