Tools API#

Configuration management#

The following class allows you to manage Cluster instruments from within Python.

Note

There is also a command-line tool for this, that comes with the Qblox instruments, named qblox-cfg. Run qblox-cfg help for its documentation.

class ConfigurationManager(identifier)[source]#

Bases: object

Class that provides configuration management functionality.

__init__(identifier)[source]#

Creates a configuration management interface object for the given device. Use close() when you’re done with the object, or a with clause:

with cfg_man(...) as cm:
    # do stuff with cm here
    pass

Note

Depending on the software running on the device and the connectivity to the device, not all features may be available. See get_protocol().

Feature availability#
Feature	`scpi/cfg`	`pnp`
`set_name`	Yes	Yes
`download_log`	Yes	No
`set_ip_config`	Yes	Yes
`update`	Yes	No
`rollback`	Yes	No
`reboot`	Yes	Yes

Parameters:: identifier (Union[str, AddressInfo, ConnectionInfo]) – Instrument identifier. See resolve().
Raises:: Exception – If we can’t connect.

close()[source]#

Closes the underlying connection. The object must not be used anymore after this call.

Return type:: None

static cmd_line(*args)[source]#

Runs the configuration manager with the given command-line arguments.

Parameters:: *args (Iterable[str]) – The command-line arguments.
Raises:: RuntimeError – If the command-line tool returns a nonzero exit status.
Return type:: None

describe(as_json=False)[source]#

Prints information about the device being connected to stdout.

Parameters:: as_json (bool) – If set to True, the structure is dumped in a machine-friendly JSON format rather than a pretty-printed table.
Return type:: None

download_log(source='app', fmt='tail', file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, tail=100)[source]#

Downloads log data from the device.

Parameters:

source (str) – The log source. Currently this must be "app" (default), "system", or "cfg_man", or the device will return an error.
fmt (Union[str, int]) –
File format:
- If "tail" (default): return the latest <tail> messages in plaintext.
- If a positive integer: return the latest <fmt> messages in plaintext.
- If "txt" or zero: return the log file currently in rotation in plaintext.
- If "tgz" or a negative integer: return all log files in rotation in a tar.gz archive.
file (Union[str, BinaryIO, TextIO]) –
The file object to write to. For textual formats, the file may be opened in either binary or unicode mode (in the latter case, the contents will be buffered in memory first); for tgz, it must be open in binary mode. If a string, this is a pattern for the filename to write to; the file will be opened internally. The following substitutions are made for convenience:
- %s -> device serial number;
- %n -> device name (be careful, device names are not necessarily valid filenames);
- %i -> address of the device we’re connecting to (usually IP+port, but will be the serial number when this is a plug & play connection).
tail (int) – If fmt is "tail", this specifies the number of lines returned. Unused otherwise.

Raises:

NotImplementedError – If the underlying protocol we’re connecting with does not support this command.
Exception – If the command failed.

Return type:

None

get_connection_info()[source]#

Returns the connection information object.

Return type:: ConnectionInfo
Returns:: ConnectionInfo The connection information object.

get_protocol()[source]#

Returns the protocol used for this connection.

Return type:: str
Returns:: str The protocol, either "scpi" or "pnp".

has_capability(cmd)[source]#

Returns whether our connection type supports the given command.

Parameters:: cmd (str) – The command name.
Return type:: bool
Returns:: bool Whether the command is supported. Note that some commands are only partially supported; in this case, this still reports True.

reboot()[source]#

Instructs the device to reboot.

Raises:

NotImplementedError – If the underlying protocol we’re connecting with does not support this command.
Exception – If the command failed.

Return type:

None

rollback()[source]#

Instructs the device to attempt a rollback to the previous version. The changes will only go into effect once the device is rebooted.

Raises:

NotImplementedError – If the underlying protocol we’re connecting with does not support this command.
Exception – If the command failed.

Return type:

None

set_ip_config(config)[source]#

Reconfigures the IP configuration of the device. Changes will only go into effect after the device is rebooted.

Note

If this is a plug & play connection, this will also reboot the device immediately.

Parameters:

config (str) –

The IP configuration. Must be one of:

a static IPv4 address including prefix length;

a static IPv6 address including prefix length;

”dhcp” to get an IPv4 address via DHCP;

a combination of an IPv4 and IPv6 configuration separated by a semicolon.

Raises:

NotImplementedError – If the underlying protocol we’re connecting with does not support this command.
Exception – If the command failed.

Return type:

None

set_name(name)[source]#

Renames the device. The name change will be processed immediately.

Parameters:

name (str) – The new name. Names may not contain newlines, backslashes, or double-quotes.

Raises:

NotImplementedError – If the underlying protocol we’re connecting with does not support this command.
Exception – If the command failed.

Return type:

None

update(package, included_slots=None, excluded_slots=None)[source]#

Updates the device with the given update file. The changes will only go into effect once the device is rebooted.

Parameters:

package (Union[str, UpdateFile]) – The update package.

Raises:

NotImplementedError – If the underlying protocol we’re connecting with does not support this command.
Exception – If the command failed.

Return type:

None

Supporting classes and functions#

class ConnectionInfo(identifier, protocol, address, slot_index, ip_config, server_version, device, all_updatable_models)#

Bases: tuple

Configuration manager connection information structure.

address#

Two-tuple of the IP address and port we need to use to connect for SCPI connections, or the device serial number for plug & play.

Type:: Union[str, tuple[str, int]]

all_updatable_models#

Set of lowercase model names that will need to be present in the update package. Must include {device}, but the cluster management module may for instance request more model names.

Type:: set[str]

device#

Device information structure.

Type:: DeviceInfo

identifier#

Device identifier or address, as passed to probe_device().

Type:: Union[str, AddressInfo]

ip_config#

The IP configuration of the device that will be applied when the device is rebooted, if known. May or may not match the address field, as the configuration may have changed since the instrument was last rebooted, and the local IP address of the instrument may differ from what we’re connecting to if NAT is involved.

Type:: str

protocol#

The protocol that must be used to connect. Can be:

"scpi" for the SCPI-based configuration manager protocol; or
"pnp" when the device is not accessible due to IP address misconfiguration.

Type:: str

server_version#

Configuration manager server version, if known. Will be None for plug & play.

Type:: Optional[tuple[int, int, int]]

slot_index#

None for entire device, slot index if only a single module in the device will be affected.

Type:: Optional[int]

class PortInfo(protocol, version, device)#

Bases: tuple

Protocol information for a particular IP/TCP port pair, supporting SCPI configuration manager protocol.

device#

Device information structure.

Type:: DeviceInfo

protocol#

The type of host we’re connected to, which will be one of the following values.

update() function from this file can be used to update the device, but other features will not work (use an older configuration manager if you need them).

"cfg_man": the configuration manager application via SCPI. This application can manage the device at the given host, but only that device.

"app": the instrument application via SCPI. This means the connection is fully-featured, including the ability to configure modules (if this is a CMM).

Type:: str

version#

Configuration manager server version.

Type:: str

connection_info_to_json(ci)[source]#

Converts a ConnectionInfo object to a JSON-serializable representation thereof.

Parameters:: ci (ConnectionInfo) – The connection information object to pretty-print.
Return type:: dict
Returns:: dict A structure using only JSON-serializable types with all the information of the ConnectionInfo object in it.

get_device_info(identifier)[source]#

Fetches a complete DeviceInfo structure for the given device.

Parameters:: identifier (Union[str, AddressInfo, ConnectionInfo]) – Instrument identifier. See resolve() for more information.
Return type:: DeviceInfo
Returns:: DeviceInfo The device information.
Raises:: RuntimeError – if we failed to connect.

pprint_connection_info(ci, output=<function info>)[source]#

Pretty-prints information about a connection information object.

Parameters:

ci (ConnectionInfo) – The connection information object to pretty-print.
output (Callable[[str], None]) – The function used for printing. Each call represents a line.

Return type:

None

probe_device(identifier, quiet=False)[source]#

Automatically detects how to manage the given device.

Parameters:

identifier (str) – Instrument identifier. See resolve() for more information.
quiet (bool) – When set, don’t log anything.

Return type:

ConnectionInfo

Returns:

ConnectionInfo The detected connection and device information.

Raises:

RuntimeError – if we failed to connect.

probe_port(host, port, timeout=10.0, slot=None)[source]#

Automatically detects what type of application is listening on the given host and port.

Parameters:

host (str) – IP address or hostname of the server to connect to.
port (int) – Port to connect to.
timeout (float) – Socket timeout in seconds.
slot (int, Optional) – Slot number to use for the connection via CMM. If None, uses port for the connection

Return type:

PortInfo

Returns:

PortInfo Information about the protocol.

Raises:

ValueError – If the configuration manager returned something we didn’t expect.

represent_address(ci)[source]#

Returns a human-readable string representation of the address.

Parameters:: ci (ConnectionInfo) – The connection information object to represent the address of.
Return type:: str
Returns:: str String representation of the address.

represent_connection(ci)[source]#

Returns a human-readable string representation of the connection.

Parameters:: ci (ConnectionInfo) – The connection information object to represent the connection of.
Return type:: str
Returns:: str String representation of the connection.

represent_device(ci)[source]#

Returns a human-readable string representation of the device we’re connecting to.

Parameters:: ci (ConnectionInfo) – The connection information object to represent the device of.
Return type:: str
Returns:: str String representation of the device.

class ArchiveExtension(value)[source]#

Bases: Enum

An enumeration.

RAUC_BUNDLE = 6#

TAR = 5#

TAR_BZ2 = 4#

TAR_GZ = 2#

TAR_XZ = 3#

ZIP = 1#

class ArchiveType(value)[source]#

Bases: Enum

An enumeration.

SQUASHFS = 6#

TAR = 5#

TAR_BZ2 = 4#

TAR_GZ = 2#

TAR_XZ = 3#

ZIP = 1#

class UpdateFile(fname, check_version=True)[source]#

Bases: object

Representation of a device update file.

__init__(fname, check_version=True)[source]#

Loads an update file.

Parameters:

fname (str) – The file to load.
check_version (bool) – Whether to throw a NotImplementedError if the minimum configuration management client version reported by the update file is newer than our client version.

close()[source]#

Cleans up any operating resources that we may have claimed.

Return type:: None

load(ci, included_slots=None, excluded_slots=None)[source]#

Loads an update file, checking whether the given update file is compatible within the given connection context. Returns a file-like object opened in binary read mode if compatible, or throws a ValueError if there is a problem.

Parameters:

ci (ConnectionInfo) – Connection information object retrieved from autoconf(), to verify that the update file is compatible, or to make it compatible, if possible.
included_slots (Optional[Iterable[int]]) – list of included slot indices. Optional, by default None.
excluded_slots (Optional[Iterable[int]]) – list of excluded slot indices. Optional, by default None.

Return type:

BinaryIO

Returns:

BinaryIO Binary file-like object for the update file. Will at least be opened for reading, and rewound to the start of the file. This may effectively be open(fname, "rb"), but could also be a tempfile.TemporaryFile to an update file specifically converted to be compatible with the given environment. It is the responsibility of the caller to close the file.

Raises:

ValueError – If there is a problem with the given update file.

needs_confirmation()[source]#

Returns whether the update file requests the user to confirm something before application, and if so, what message should be printed.

Return type:: Optional[str]
Returns:: Optional[str] None if there is nothing exceptional about this file, otherwise this is the confirmation message.

pprint(output=<function info>)[source]#

Pretty-prints the update file metadata.

Parameters:: output (Callable[[str], None]) – The function used for printing. Each call represents a line.
Return type:: None

summarize()[source]#

Returns a summary of the update file format.

Return type:: str
Returns:: str Update file summary.

Plug & Play#

The following class allows you to send Qblox Plug & Play commands from within Python.

Note

There is also a command-line tool for this, that comes with the Qblox instruments, named qblox-pnp. Run qblox-pnp help for its documentation.

class PlugAndPlay[source]#

Bases: object

Class that provides device discovery and IP address (re)configuration functionality, for instance to convert customer-controlled device names or serial numbers to IP addresses we can connect to via the usual interfaces.

__init__()[source]#

Creates a plug & play interface object. Use close() when you’re done with the object, or a with clause:

with PlugAndPlay() as p:
    # do stuff with p here
    pass

Raises:: OSError – If creating the network socket fails.

close()[source]#

Closes the underlying socket. The object must not be used anymore after this call.

Return type:: None

static cmd_line(*args)[source]#

Runs the plug & play command-line tool with the given arguments.

Parameters:: *args (Iterable[str]) – The command-line arguments.
Return type:: Any
Returns:: Any If the given command logically returns something, it will be returned as a Python value in addition to being printed as a string. Otherwise, None will be returned.
Raises:: RuntimeError – If the command-line tool returns a nonzero exit status.

describe(serial_or_name, retries=3, timeout=1.0)[source]#

Returns the device description structure corresponding to the device with the given serial number or customer-given name.

Parameters:

serial_or_name (str) – Serial number or customer-given name of the device that is to be queried.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Return type:

dict

Returns:

dict The device description structure.

Raises:

TypeError – If serial_or_name is invalid.
ValueError – If serial_or_name is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.

get_ip(serial_or_name, retries=3, timeout=1.0)[source]#

Returns the IP address of the device with the given serial number or customer-given name.

Parameters:

serial_or_name (str) – Serial number or customer-given name of the device that is to be queried.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Return type:

str

Returns:

str The IP address of the device.

Raises:

TypeError – If serial_or_name is invalid.
ValueError – If serial_or_name is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.
KeyError – If the device response did not contain the requested information.

get_name(serial, retries=3, timeout=1.0)[source]#

Returns the customer-given name of the device with the given serial number.

Parameters:

serial (str) – Serial number of the device that is to be queried.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Return type:

str

Returns:

str The customer-given name of the device.

Raises:

TypeError – If serial is invalid.
ValueError – If serial is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.
KeyError – If the device response did not contain the requested information.

get_serial(name, retries=3, timeout=1.0)[source]#

Returns the serial number of the device with the given customer-given name.

Parameters:

name (str) – Customer-given name of the device that is to be queried.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Return type:

str

Returns:

str The serial number of the device.

Raises:

TypeError – If name is invalid.
ValueError – If name is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.
KeyError – If the device response did not contain the requested information.

identify(serial_or_name, retries=3, timeout=1.0)[source]#

Visually identifies the device with the given serial number or customer-given name by having it blink its LEDs for a while.

Parameters:

serial_or_name (str) – Serial number of the device that is to be identified.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Raises:

TypeError – If serial_or_name is invalid.
ValueError – If serial_or_name is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.

Return type:

None

identify_all(count=3)[source]#

Instructs all devices visible on the network to blink their LEDs.

Parameters:: count (int) – Number of times to repeat the command packet, to reduce the odds of packet loss being a problem.
Raises:: OSError – If transmission or reception fails.
Return type:: None

list_devices(timeout=1.0)[source]#

Lists all observable devices on the network.

Parameters:: timeout (float) – Timeout in seconds to wait for responses.
Return type:: dict[str, dict]
Returns:: dict[str, dict] Mapping from serial number to device description record as returned by the device. If a device returned an invalid structure, its dict will be {}.
Raises:: OSError – If transmission or reception fails.

print_devices(timeout=1.0)[source]#

Like list_devices(), but prints a user-friendly device list instead of returning a data structure.

Parameters:: timeout (float) – Timeout in seconds to wait for responses.
Raises:: OSError – If transmission or reception fails.
Return type:: None

reboot(serial_or_name, retries=3, timeout=1.0)[source]#

Reboots the device with the given serial number or customer-given name.

Parameters:

serial_or_name (str) – Serial number of the device that is to be rebooted.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Raises:

TypeError – If serial_or_name is invalid.
ValueError – If serial_or_name is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.

Return type:

None

reboot_all(count=3)[source]#

Instructs all devices on the network to reboot.

Parameters:: count (int) – Number of times to repeat the command packet, to reduce the odds of packet loss being a problem.
Raises:: OSError – If transmission or reception fails.
Return type:: None

recover_device()[source]#

Attempts to recover a device with a severely broken IP configuration, by instructing ALL devices on the network to revert back to 192.168.0.2/24. ONLY RUN THIS COMMAND WHEN YOU ARE ONLY CONNECTED TO A SINGLE DEVICE, OR YOU WILL GET IP ADDRESS CONFLICTS.

Raises:: OSError – If recovery packet transmission fails.
Return type:: None

set_all_dhcp(count=3)[source]#

Instructs all devices on the network to reboot and obtain an IP address via DHCP.

Parameters:: count (int) – Number of times to repeat the command packet, to reduce the odds of packet loss being a problem.
Raises:: OSError – If transmission or reception fails.
Return type:: None

set_ip(serial_or_name, ip_address, retries=3, timeout=1.0)[source]#

Adjusts the IP address configuration of the device with the given serial number or customer-given name. The device will reboot as a result of this.

Parameters:

serial_or_name (str) – Serial number or customer-given name of the device that is to be reconfigured.
ip_address (str) – The new IP address configuration for the device. This may be an IPv4 address including prefix length (x.x.x.x/x), an IPv6 address including prefix length (e.g. x:x::x:x/x), a combination thereof separated via a semicolon, or the string dhcp to have the device obtain an IPv4 address via DHCP.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Raises:

TypeError – If serial_or_name is invalid.
ValueError – If serial_or_name is invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.

Return type:

None

set_name(serial_or_name, new_name, retries=3, timeout=1.0)[source]#

Renames the device with the given serial number or name.

Parameters:

serial_or_name (str) – Serial number or customer-given name of the device that is to be reconfigured.
new_name (str) – The new customer-given name for the device. May not contain newlines, double quotes, or backslashes.
retries (int) – Number of times to retry sending the command, if no response is received.
timeout (float) – Timeout in seconds to wait for a response, per retry.

Raises:

TypeError – If serial_or_name or new_name are invalid.
ValueError – If serial_or_name or new_name are invalid.
OSError – If transmission or reception fails.
TimeoutError – If no response is received from the device.
RuntimeError – If an unexpected response is received from the device.

Return type:

None

Supporting classes and functions#

resolve(identifier)[source]#

Converts a device identifier to an IP address or (if only reachable via plug and play) a serial number. For IP connections, also returns the ports that the device should be listening on.

Parameters:

identifier (Union[str, AddressInfo]) –

If a string, this can be one of the following things:

"[ip://]<ip-address>[/#]",

"[pnp://]<device-name>[/#]",

"[pnp://]<serial-number>[/#]", or

"[ip://]<hostname>[/#]",

where:

<ip-address> is a valid IPv4 or IPv6 address for the device to be resolved;

<device-name> is the customer-specified name of the instrument (programmed into it with qblox-cfg, qblox-pnp, or the set_name() method);

<serial-number> is the serial number of the instrument;

<hostname> is a hostname that will resolve to the IP address of the instrument via DNS (some routers support this if the device connects via DHCP; the hostname requested by the device will be its customer-specified name in lowercase, using dashes (-) for sequences of non-alphanumeric characters);

either ip:// or pnp:// may be prefixed to disambiguate between the various methods of device identification, if necessary; and

the optional /# suffix may be used for cluster devices to return information for a specific cluster module, where # is the slot index of the module.

The four identification methods will be attempted in the sequence shown.

If an AddressInfo object is passed as input, this function simply returns it as-is.

Return type:

AddressInfo

Returns:

AddressInfo Address information structure.

Raises:

ValueError – If the identifier is invalid.
RuntimeError – If we failed to determine what this identifier is.

class AddressInfo(protocol, address, slot_index, scpi_port, cfg_port, zmq_rr_port, zmq_ps_port)#

Bases: tuple

Connection information structure. Can be constructed from an instrument identifier via resolve().

address#

IP address string for IP connections, or the device serial number for plug & play.

Type:: str

cfg_port#

The port number for configuration manager connections.

Type:: int

protocol#

The protocol that must be used to connect. Can be:

"ip" for a normal IP-based connection; or
"pnp" when the device is not accessible due to IP address misconfiguration.

Type:: str

scpi_port#

The port number for SCPI connections.

Type:: int

slot_index#

For clusters, this specifies which specific module to connect to, if any. If None, the whole cluster will be treated as a single instrument.

Type:: Optional[int]

zmq_ps_port#

The port number for Qblox native ZeroMQ/CBOR PUB-SUB connections.

Type:: int

zmq_rr_port#

The port number for Qblox native ZeroMQ/CBOR REQ-REP connections.

Type:: int

Build information#

The following functions and classes allow you to programmatically retrieve version and build information for various components.

Information about Qblox Instruments#

get_build_info()[source]#

Get build information for Qblox Instruments.

Return type:: BuildInfo
Returns:: BuildInfo Build information structure for Qblox Instruments.

class BuildInfo(version, build, hash, dirty)[source]#

Bases: object

Class representing build information for a particular component.

__init__(version, build, hash, dirty)[source]#

Makes a build information object.

Parameters:

version (Union[str, tuple[int, int, int]]) – Either a canonical version string or a three-tuple of integers.
build (Union[str, int, datetime],) – The build timestamp, either as a string formatted like “17/11/2021-19:04:53” (as used in *IDN?), a Unix timestamp in seconds, or a Python datetime object.
hash (Union[str, int]) – The git hash of the repository that the build was run from, either as a hex string with at least 8 characters, or as an integer. If 0x is prefixed, the hash may have less than 8 digits, implying zeros in front.
dirty (Union[str, bool]) – Whether the git repository was dirty at the time of the build, either as a 0 or 1 string (as in *IDN?) or as the boolean itself.

classmethod from_dict(build_data)[source]#

Constructs a build information structure from a JSON-capable dict, as used in ZeroMQ/CBOR descriptions, plug&play descriptions, update file metadata, and various other places.

Parameters:

build_data (dict) –

Dictionary with (at least) the following keys:

"version": iterable of three integers representing the version;

"build": Unix timestamp in seconds representing the build timestamp;

"hash": the first 8 hex digits of the git hash as an integer; and

"dirty": boolean dirty flag.

Return type:

BuildInfo

Returns:

BuildInfo The build information structure.

classmethod from_idn(idn, prefix='')[source]#

Constructs a build information structure from an *IDN? string.

Parameters:

idn (str) – The *IDN? string.
prefix (str) – The prefix used for each key (currently fw, kmod, sw, or cfgMan).

Return type:

Optional[BuildInfo]

Returns:

Optional[BuildInfo] The build information structure if data is available for the given key, or None if not.

to_dict()[source]#

Formats this build information object as a JSON-capable dict, as used in ZeroMQ/CBOR descriptions, plug&play descriptions, update file metadata, and various other places.

Return type:

dict

Returns:

dict The generated dictionary, having the following keys:

"version": iterable of three integers representing the version;

"build": Unix timestamp in seconds representing the build timestamp;

"hash": the first 8 hex digits of the git hash as an integer; and

"dirty": boolean dirty flag.

to_idn(prefix='')[source]#

Formats this build information object in the same way *IDN? is formatted.

Parameters:: prefix (str) – The prefix used for each key (currently fw, kmod, sw, or cfgMan).
Return type:: str
Returns:: str The part of the *IDN? string for this build information object.

to_idn_dict()[source]#

Formats this build information object as a human-readable JSON-capable dict, as used in get_idn.

Return type:

dict

Returns:

dict The generated dictionary, having the following keys:

"version": string representation of the version;

"build": string representation of timestamp in seconds representing the build timestamp;

"hash": string representation of the first 8 hex digits of the git hash; and

"dirty": boolean dirty flag.

to_tuple()[source]#

Formats this build information object as a tuple for ordering purposes.

Return type:: tuple
Returns:: tuple A tuple, containing all the information in this structure in a canonical format.

property build: datetime#

The build timestamp as a datetime object.

Type:: datetime

property build_iso: str#

The build time as a string, formatted using the ISO date format.

Type:: str

property build_str: str#

The build time as a string, as formatted for *IDN?.

Type:: str

property build_unix: int#

The build time as a unix timestamp in seconds.

Type:: int

property dirty: bool#

Whether the repository was dirty during the build.

Type:: bool

property dirty_str: str#

The dirty flag as a 0 or 1 string (as used for *IDN?).

Type:: str

property hash: int#

The git hash as an integer.

Type:: int

property hash_str: str#

The git hash as a string.

Type:: str

property version: tuple[int, int, int]#

The version as a three-tuple.

Type:: tuple[int, int, int]

property version_str: str#

The version as a string.

Type:: str

Information about an instrument#

get_device_info(identifier)[source]#

Fetches a complete DeviceInfo structure for the given device.

Parameters:: identifier (Union[str, AddressInfo, ConnectionInfo]) – Instrument identifier. See resolve() for more information.
Return type:: DeviceInfo
Returns:: DeviceInfo The device information.
Raises:: RuntimeError – if we failed to connect.

class DeviceInfo(manufacturer, model, name='unknown', serial=None, is_extended_instrument=False, is_rf=False, sw_build=None, fw_build=None, kmod_build=None, cfg_man_build=None, modules=None)[source]#

Bases: object

Class representing the build and model information of a device. Has the same information content as what *DESCribe? returns.

__init__(manufacturer, model, name='unknown', serial=None, is_extended_instrument=False, is_rf=False, sw_build=None, fw_build=None, kmod_build=None, cfg_man_build=None, modules=None)[source]#

classmethod from_dict(description)[source]#

Constructs a device information structure from a JSON-capable dict, as used in ZeroMQ/CBOR descriptions, plug&play descriptions, update file metadata, and various other places.

Parameters:

description (dict) –

Dictionary with the following keys:

"manufacturer": manufacturer name (string);

"model": model name (string);

"name": device name (string);

"ser": serial number (string);

"is_extended_instrument": flag indicating if the device is an extended instrument (boolean);

"is_rf": flag indicating if the device has RF functionality (boolean);

"sw": application build information (dict);

"fw": FPGA firmware build information (dict);

"kmod": kernel module build information (dict);

"cfg_man": configuration management build information (dict);

"modules": dictionary of modules (optional).

Return type:

DeviceInfo

Returns:

DeviceInfo The build information structure.

classmethod from_idn(idn)[source]#

Constructs a device information structure from an *IDN? string.

Parameters:: idn (str) – The *IDN? string.
Return type:: DeviceInfo
Returns:: DeviceInfo The parsed device information structure.

get_build_info(key)[source]#

Returns build information for the given key.

Parameters:

key (str) –

The key. Must be one of:

"sw": returns the application build info;

"fw": returns the FPGA firmware build info;

"kmod": returns the kernel module build info; or

"cfg_man" or "cfgMan": returns the configuration manager build info.

Return type:

Optional[BuildInfo]

Returns:

Optional[BuildInfo] The build information structure, if known.

Raises:

KeyError – For unknown keys.

set_modules_from_idn(modules_description)[source]#

Return type:: None

to_dict()[source]#

Formats this device information object as a JSON-capable dict, as used in ZeroMQ/CBOR descriptions, plug&play descriptions, update file metadata, and various other places.

Return type:

dict

Returns:

dict The generated dictionary, having the following keys:

"manufacturer": manufacturer name (string);

"model": model name (string);

"name": device name (string);

"ser": serial number (string);

"is_extended_instrument": flag indicating if the device is an
extended instrument (boolean);

"is_rf": flag indicating if the device has RF functionality
(boolean);

"sw": application build information (dict);

"fw": FPGA firmware build information (dict);

"kmod": kernel module build information (dict);

"cfg_man": configuration management build information (dict);

"modules": dictionary of modules (optional).

Some keys may be omitted if the information is not available.

to_idn()[source]#

Formats this device information object in the same way *IDN? is formatted.

Return type:: str
Returns:: str The *IDN? string.

to_idn_dict()[source]#

Formats this device information object as a human-readable JSON-capable dict, as used get_idn.

Return type:

dict

Returns:

dict The generated dictionary, having the following keys:

"manufacturer": manufacturer name (string);

"model": model name (string);

"serial_number": serial number (string);

"firmware": build info (dict);

"fpga": FPGA firmware build information (dict);

"kernel_mod": kernel module build information (dict);

"application": application build information (dict); and

"driver": driver build information (dict);

Some keys may be omitted if the information is not available.

to_tuple()[source]#

Formats this device information object as a tuple for ordering purposes.

Return type:: tuple
Returns:: tuple A tuple, containing all the information in this structure in a canonical format.

update_name(new_name)[source]#

Update the name of the device if the new name is not “unknown”.

Parameters:: new_name (str) – The new name to set.
Return type:: None

property cfg_man_build: BuildInfo | None#

The configuration management build information, if known.

Type:: Optional[BuildInfo]

property fw_build: BuildInfo | None#

The FPGA firmware build information, if known.

Type:: Optional[BuildInfo]

property is_extended_instrument: bool#

Indicates whether the module is an extended instrument.

Type:: bool

property is_rf: bool#

Indicates whether the module has RF functionality.

Type:: bool

property kmod_build: BuildInfo | None#

The kernel module build information, if known.

Type:: Optional[BuildInfo]

property manufacturer: str#

The manufacturer name, in lowercase_with_underscores format.

Type:: str

property model: str#

The model name, in lowercase_with_underscores format.

Type:: str

property modules: dict[str, DeviceInfo] | None#

The managed modules, if any.

Type:: Optional[dict[str, DeviceInfo]]

property name: str#

The customer-specified name of the instrument.

Type:: str

property serial: str | None#

The serial number, if known.

Type:: Optional[str]

property sw_build: BuildInfo | None#

The software/application build information, if known.

Type:: Optional[BuildInfo]