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 qblox_instruments.ConfigurationManager(identifier: str | AddressInfo | ConnectionInfo)[source]#

Bases: object

Class that provides configuration management functionality.

__init__(identifier: str | AddressInfo | ConnectionInfo)[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

legacy

pnp

set_name

Yes

No

Yes

download_log

Yes

tgz only

No

set_ip_config

Yes

192.168.x.x/24 only

Yes

update

Yes

Yes

No

rollback

Yes

Yes

No

reboot

Yes

Yes

Yes

scpi will be used if available, but:

  • devices running an old software version may not support it, in which case legacy will be used; and

  • if the embedded software version is new enough but the device IP configuration is incompatible with your network settings, pnp will be used.

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.

Parameters:

None –

Return type:

None

get_connection_info() → ConnectionInfo[source]#

Returns the connection information object.

Parameters:

None –

Returns:

The connection information object.

Return type:

ConnectionInfo

get_protocol() → str[source]#

Returns the protocol used for this connection.

Parameters:

None –

Returns:

The protocol, either "scpi", "legacy", or "pnp".

Return type:

str

has_capability(cmd: str) → bool[source]#

Returns whether our connection type supports the given command.

Parameters:

cmd (str) – The command name.

Returns:

Whether the command is supported. Note that some commands are only partially supported; in this case, this still reports True.

Return type:

bool

describe(as_json: bool = False)[source]#

Prints information about the device being connected to 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.

download_log(source: str = 'app', fmt: str | int = 'tail', file: str | ~typing.BinaryIO | ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, tail: int = 100) → None[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.

Return type:

None

Raises:

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

  • Exception – If the command failed.

set_name(name: str) → None[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.

Return type:

None

Raises:

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

  • Exception – If the command failed.

set_ip_config(config: str) → None[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.

Return type:

None

Raises:

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

  • Exception – If the command failed.

update(package: str | UpdateFile) → 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.

Return type:

None

Raises:

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

  • Exception – If the command failed.

rollback() → None[source]#

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

Parameters:

None –

Return type:

None

Raises:

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

  • Exception – If the command failed.

reboot() → None[source]#

Instructs the device to reboot.

Parameters:

None –

Return type:

None

Raises:

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

  • Exception – If the command failed.

static cmd_line(*args: Iterable[str]) → None[source]#

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

Parameters:

*args (Iterable[str]) – The command-line arguments.

Return type:

None

Raises:

RuntimeError – If the command-line tool returns a nonzero exit status.

Supporting classes and functions#

class qblox_instruments.cfg_man.probe.PortInfo(protocol, version, device)#

Bases: tuple

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

device#

Device information structure.

Type:

DeviceInfo

protocol#

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

  • "legacy_cfg_man": a legacy configuration manager. The 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).

  • "legacy_app": a legacy application without configuration management commands.

  • "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

qblox_instruments.cfg_man.probe.probe_port(host: str, port: int, version: Tuple[int, int, int], timeout: float = 10.0) → PortInfo[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.

  • version (Tuple[int, int, int]) – Our client version.

  • timeout (float) – Socket timeout in seconds.

Returns:

Information about the protocol.

Return type:

PortInfo

Raises:

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

class qblox_instruments.cfg_man.probe.ConnectionInfo(identifier, protocol, address, slot_index, ip_config, server_version, client_version, device, name, all_models)#

Bases: tuple

Configuration manager connection information structure.

address#

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

Type:

Union[str, tuple[str, int]]

all_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]

client_version#

Configuration manager client version.

Type:

tuple[int, int, int]

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

name#

Customer-specified name of the instrument, if known.

Type:

Optional[str]

protocol#

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

  • "legacy" for the legacy configuration manager protocol;

  • "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]

qblox_instruments.cfg_man.probe.represent_address(ci: ConnectionInfo) → str[source]#

Returns a human-readable string representation of the address.

Parameters:

ci (ConnectionInfo) – The connection information object to represent the address of.

Returns:

String representation of the address.

Return type:

str

qblox_instruments.cfg_man.probe.represent_connection(ci: ConnectionInfo) → str[source]#

Returns a human-readable string representation of the connection.

Parameters:

ci (ConnectionInfo) – The connection information object to represent the connection of.

Returns:

String representation of the connection.

Return type:

str

qblox_instruments.cfg_man.probe.represent_device(ci: ConnectionInfo) → str[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.

Returns:

String representation of the device.

Return type:

str

qblox_instruments.cfg_man.probe.pprint_connection_info(ci: ~qblox_instruments.cfg_man.probe.ConnectionInfo, output: ~typing.Callable[[str], None] = <function info>) → None[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.

qblox_instruments.cfg_man.probe.connection_info_to_json(ci: ConnectionInfo) → dict[source]#

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

Parameters:

ci (ConnectionInfo) – The connection information object to pretty-print.

Returns:

A structure using only JSON-serializable types with all the information of the ConnectionInfo object in it.

Return type:

dict

qblox_instruments.cfg_man.probe.probe_device(identifier: str | AddressInfo | ConnectionInfo, quiet: bool = False) → ConnectionInfo[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.

Returns:

The detected connection and device information.

Return type:

ConnectionInfo

Raises:

RuntimeError – if we failed to connect.

qblox_instruments.cfg_man.probe.get_device_info(identifier: str | AddressInfo | ConnectionInfo) → DeviceInfo[source]#

Fetches a complete DeviceInfo structure for the given device.

Parameters:

identifier (Union[str, AddressInfo, ConnectionInfo]) – Instrument identifier. See resolve() for more information.

Returns:

The device information.

Return type:

DeviceInfo

Raises:

RuntimeError – if we failed to connect.

class qblox_instruments.cfg_man.update_file.UpdateFile(fname: str, check_version: bool = True)[source]#

Bases: object

Representation of a device update file.

__init__(fname: str, check_version: bool = 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.

needs_confirmation() → str | None[source]#

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

Returns:

None if there is nothing exceptional about this file, otherwise this is the confirmation message.

Return type:

Optional[str]

summarize() → str[source]#

Returns a summary of the update file format.

Returns:

Update file summary.

Return type:

str

pprint(output: ~typing.Callable[[str], None] = <function info>) → None[source]#

Pretty-prints the update file metadata.

Parameters:

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

load(ci: ConnectionInfo) → BinaryIO[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.

Returns:

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.

Return type:

BinaryIO

Raises:

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

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 qblox_instruments.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.

list_devices(timeout: float = 1.0) → Dict[str, dict][source]#

Lists all observable devices on the network.

Parameters:

timeout (float) – Timeout in seconds to wait for responses.

Returns:

Mapping from serial number to device description record as returned by the device. If a device returned an invalid structure, its dict will be {}.

Return type:

Dict[str, dict]

Raises:

OSError – If transmission or reception fails.

print_devices(timeout: float = 1.0) → None[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.

identify(serial_or_name: str, retries: int = 3, timeout: float = 1.0) → None[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 respone is received from the device.

  • RuntimeError – If an unexpected response is received from the device.

identify_all(count: int = 3) → None[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.

describe(serial_or_name: str, retries: int = 3, timeout: float = 1.0) → dict[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.

Returns:

The device description structure.

Return type:

dict

Raises:

  • TypeError – If serial_or_name is invalid.

  • ValueError – If serial_or_name is invalid.

  • OSError – If transmission or reception fails.

  • TimeoutError – If no respone is received from the device.

  • RuntimeError – If an unexpected response is received from the device.

get_serial(name: str, retries: int = 3, timeout: float = 1.0) → str[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.

Returns:

The serial number of the device.

Return type:

str

Raises:

  • TypeError – If name is invalid.

  • ValueError – If name is invalid.

  • OSError – If transmission or reception fails.

  • TimeoutError – If no respone 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: str, retries: int = 3, timeout: float = 1.0) → str[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.

Returns:

The customer-given name of the device.

Return type:

str

Raises:

  • TypeError – If serial is invalid.

  • ValueError – If serial is invalid.

  • OSError – If transmission or reception fails.

  • TimeoutError – If no respone 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.

set_name(serial_or_name: str, new_name: str, retries: int = 3, timeout: float = 1.0) → None[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 respone is received from the device.

  • RuntimeError – If an unexpected response is received from the device.

get_ip(serial_or_name: str, retries: int = 3, timeout: float = 1.0) → str[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.

Returns:

The IP address of the device.

Return type:

str

Raises:

  • TypeError – If serial_or_name is invalid.

  • ValueError – If serial_or_name is invalid.

  • OSError – If transmission or reception fails.

  • TimeoutError – If no respone 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.

set_ip(serial_or_name: str, ip_address: str, retries: int = 3, timeout: float = 1.0) → None[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 respone is received from the device.

  • RuntimeError – If an unexpected response is received from the device.

set_all_dhcp(count: int = 3) → None[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.

reboot(serial_or_name: str, retries: int = 3, timeout: float = 1.0) → None[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 respone is received from the device.

  • RuntimeError – If an unexpected response is received from the device.

reboot_all(count: int = 3) → None[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.

recover_device() → None[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.

static cmd_line(*args: Iterable[str]) → Any[source]#

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

Parameters:

*args (Iterable[str]) – The command-line arguments.

Returns:

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.

Return type:

Any

Raises:

RuntimeError – If the command-line tool returns a nonzero exit status.

Supporting classes and functions#

qblox_instruments.resolve(identifier: str | AddressInfo) → AddressInfo[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.

Returns:

Address information structure.

Return type:

AddressInfo

Raises:

  • ValueError – If the identifier is invalid.

  • RuntimeError – If we failed to determine what this identifier is.

class qblox_instruments.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. For Pulsar devices, this should always be None.

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#

qblox_instruments.get_build_info() → BuildInfo[source]#

Get build information for Qblox Instruments.

Returns:

Build information structure for Qblox Instruments.

Return type:

BuildInfo

class qblox_instruments.BuildInfo(version: str | Tuple[int, int, int], build: str | int | datetime, hash: str | int, dirty: str | bool)[source]#

Bases: object

Class representing build information for a particular component.

__init__(version: str | Tuple[int, int, int], build: str | int | datetime, hash: str | int, dirty: str | bool)[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.

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

property build: datetime#

The build timestamp as a datetime object.

Type:

datetime

property build_str: str#

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

Type:

str

property build_iso: str#

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

Type:

str

property build_unix: int#

The build time as a unix timestamp in seconds.

Type:

int

property hash: int#

The git hash as an integer.

Type:

int

property hash_str: str#

The git hash as a string.

Type:

str

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

classmethod from_idn(idn: str, prefix: str = '') → BuildInfo | None[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).

Returns:

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

Return type:

Optional[BuildInfo]

to_idn(prefix: str = '') → str[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).

Returns:

The part of the *IDN? string for this build information object.

Return type:

str

classmethod from_dict(build_data: dict) → BuildInfo[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.

Returns:

The build information structure.

Return type:

BuildInfo

to_dict() → 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.

Parameters:

None –

Returns:

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.

Return type:

dict

to_idn_dict() → dict[source]#

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

Returns:

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.

Return type:

dict

to_tuple() → tuple[source]#

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

Parameters:

None –

Returns:

A tuple, containing all the information in this structure in a canonical format.

Return type:

tuple

Information about an instrument#

qblox_instruments.get_device_info(identifier: str | AddressInfo | ConnectionInfo) → DeviceInfo[source]#

Fetches a complete DeviceInfo structure for the given device.

Parameters:

identifier (Union[str, AddressInfo, ConnectionInfo]) – Instrument identifier. See resolve() for more information.

Returns:

The device information.

Return type:

DeviceInfo

Raises:

RuntimeError – if we failed to connect.

class qblox_instruments.DeviceInfo(manufacturer: str, model: str, serial: str | None = None, sw_build: BuildInfo | None = None, fw_build: BuildInfo | None = None, kmod_build: BuildInfo | None = None, cfg_man_build: BuildInfo | None = None)[source]#

Bases: object

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

__init__(manufacturer: str, model: str, serial: str | None = None, sw_build: BuildInfo | None = None, fw_build: BuildInfo | None = None, kmod_build: BuildInfo | None = None, cfg_man_build: BuildInfo | None = None)[source]#
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 device: str#

The model name, in lowercase_with_underscores format.

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]

property fw_build: BuildInfo | None#

The FPGA firmware build information, if known.

Type:

Optional[BuildInfo]

property kmod_build: BuildInfo | None#

The kernel module build information, if known.

Type:

Optional[BuildInfo]

property cfg_man_build: BuildInfo | None#

The configuration management build information, if known.

Type:

Optional[BuildInfo]

get_build_info(key: str) → BuildInfo | None[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.

Returns:

The build information structure, if known.

Return type:

Optional[BuildInfo]

Raises:

KeyError – For unknown keys.

classmethod from_idn(idn: str) → DeviceInfo[source]#

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

Parameters:

idn (str) – The *IDN? string.

Returns:

The parsed device information structure.

Return type:

DeviceInfo

to_idn() → str[source]#

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

Returns:

The *IDN? string.

Return type:

str

classmethod from_dict(description: dict) → DeviceInfo[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);

  • "ser": serial number (string);

  • "sw": application build information (dict);

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

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

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

Returns:

The build information structure.

Return type:

DeviceInfo

to_dict() → 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.

Returns:

The generated dictionary, having the following keys:

  • "manufacturer": manufacturer name (string);

  • "model": model name (string);

  • "ser": serial number (string);

  • "sw": application build information (dict);

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

  • "kmod": kernel module build information (dict); and/or

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

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

Return type:

dict

to_idn_dict() → dict[source]#

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

Returns:

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.

Return type:

dict

to_tuple() → tuple[source]#

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

Returns:

A tuple, containing all the information in this structure in a canonical format.

Return type:

tuple