Configuration management¶

The following class allows you to manage Pulsar and 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: Union[str, AddressInfo, ConnectionInfo])[source]¶

Bases: object

Class that provides configuration management functionality.

__init__(identifier: Union[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

download_log(source: str = 'app', fmt: ~typing.Union[str, int] = 'tail', file: ~typing.Union[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: Union[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.probe_device(identifier: Union[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: Union[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() → Optional[str][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.