# ----------------------------------------------------------------------------
# Description : "Smart" automatic configuration for connecting to a host
# Git repository : https://gitlab.com/qblox/packages/software/qblox_instruments.git
# Copyright (C) Qblox BV (2021)
# ----------------------------------------------------------------------------
# -- include -----------------------------------------------------------------
import struct
import socket
from collections import namedtuple
from typing import Tuple, Callable, Union
from qblox_instruments.build import DeviceInfo, BuildInfo
from qblox_instruments.pnp import (
PNP_PORT,
CMM_SLOT_INDEX,
AddressInfo,
PlugAndPlay,
resolve,
)
from qblox_instruments.scpi import CfgMan
from qblox_instruments.ieee488_2 import IpTransport
from qblox_instruments.cfg_man.legacy import (
exchange_version,
send_msg,
recv_msg,
recv_ack,
)
from qblox_instruments.cfg_man.const import VERSION
import qblox_instruments.cfg_man.log as log
# -- probe_port() ------------------------------------------------------------
# Result of probe_port()
PortInfo = namedtuple("PortInfo", ["protocol", "version", "device"])
PortInfo.__doc__ = """
Protocol information for a particular IP/TCP port pair, supporting the legacy
configuration manager protocol and SCPI.
"""
PortInfo.protocol.__doc__ = """
:str: 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).
"""
PortInfo.version.__doc__ = """
:str: Configuration manager server version.
"""
PortInfo.device.__doc__ = """
:DeviceInfo: Device information structure.
"""
# ----------------------------------------------------------------------------
[docs]
def probe_port(
host: str, port: int, version: Tuple[int, int, int], timeout: float = 10.0
) -> PortInfo:
"""
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
-------
PortInfo
Information about the protocol.
Raises
------
ValueError
If the configuration manager returned something we didn't expect.
"""
# Set default return values.
protocol = "unknown"
device = None
server_version = (0, 0, 0)
# Open the connection.
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.settimeout(timeout)
sock.connect((host, port))
# Send a dummy version in the old protocol format to get past the
# version exchange. Note that we always reconnect anyway, so it
# doesn't matter that this isn't the real version. What does matter
# is that it consists exclusively of characters illegal in SCPI.
send_msg(sock, b"\xFF\xFF\xFF")
# Send a SCPI command encapsulated in the old format. Again, the old
# format will only send bytes here that SCPI doesn't recognize and
# ignores with an error.
send_msg(sock, b"\nSYST:ERR?\n")
# The old server responds to unknown commands with a disconnection, so
# it will "respond" to the above sequence with only its version
# message (which it sends immediately after accepting the conneciton)
# followed by a disconnection event. The version message starts with a
# 0x03, since that's the LSB of the size of the version structure.
# SCPI on the other hand will respond to the SYST:ERR?, since that's
# the only thing it recognizes in the stream of garbage we sent. This
# message always starts with ASCII '-', the sign of the error code.
r = sock.recv(1)
if r == b"\x03":
# Okay, so this is a legacy configuration manager.
protocol = "legacy_cfg_man"
# Open a new connection that follows the protocol properly to get
# version and build information.
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.settimeout(timeout)
sock.connect((host, port))
# Do a proper handshake this time.
server_version = exchange_version(sock, version)
# Query device information.
send_msg(sock, b"idn")
manufacturer = (
recv_msg(sock).decode(encoding="utf-8", errors="replace").strip()
)
model = recv_msg(sock).decode(encoding="utf-8", errors="replace").strip()
build_data = recv_msg(sock)
recv_ack(sock)
# Unpack binary build information.
*version, build, hsh, dirty = struct.unpack("BBBxIII", build_data)
device = DeviceInfo(
manufacturer,
model,
cfg_man_build=BuildInfo(version, build, hsh, bool(dirty)),
)
elif r == b"-":
# This is one of the three options based on SCPI. We can determine all
# we need to know with a single *IDN? call, so let's go.
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.settimeout(timeout)
sock.connect((host, port))
sock.sendall(b"*IDN?\n")
resp = b""
while True:
buf = sock.recv(1024)
buf = buf.split(b"\n")
resp += buf[0]
if len(buf) > 1:
break
idn = resp.decode(encoding="utf-8", errors="replace").strip()
# Unpack the response.
device = DeviceInfo.from_idn(idn)
# Determine which connection type we are based on the existence of the
# app and cfg_man keys in BuildInfo.
if "cfg_man" in device:
server_version = device.cfg_man_build.version
if "sw" in device:
protocol = "app"
else:
protocol = "cfg_man"
else:
if "sw" in device:
protocol = "legacy_app"
else:
raise ValueError(
"received unexpected response during protocol detection"
)
else:
raise ValueError("received unexpected response during protocol detection")
return PortInfo(protocol, server_version, device)
# -- probe_device() ----------------------------------------------------------
# Result of probe_device()
ConnectionInfo = namedtuple(
"ConnectionInfo",
[
"identifier",
"protocol",
"address",
"slot_index",
"ip_config",
"server_version",
"client_version",
"device",
"name",
"all_models",
],
)
ConnectionInfo.__doc__ = """
Configuration manager connection information structure.
"""
ConnectionInfo.identifier.__doc__ = """
:Union[str, AddressInfo]: Device identifier or address, as passed to
:func:`~probe_device()`.
"""
ConnectionInfo.protocol.__doc__ = """
:str: 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.
"""
ConnectionInfo.address.__doc__ = """
:Union[str, tuple[str, int]]: 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.
"""
ConnectionInfo.slot_index.__doc__ = """
:Optional[int]: None for entire device, slot index if only a single module in
the device will be affected.
"""
ConnectionInfo.ip_config.__doc__ = """
:str: 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.
"""
ConnectionInfo.server_version.__doc__ = """
:Optional[tuple[int, int, int]]: Configuration manager server version, if
known. Will be None for plug & play.
"""
ConnectionInfo.client_version.__doc__ = """
:tuple[int, int, int]: Configuration manager client version.
"""
ConnectionInfo.device.__doc__ = """
:DeviceInfo: Device information structure.
"""
ConnectionInfo.name.__doc__ = """
:Optional[str]: Customer-specified name of the instrument, if known.
"""
ConnectionInfo.all_models.__doc__ = """
:set[str]: 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.
"""
# ----------------------------------------------------------------------------
[docs]
def represent_address(ci: ConnectionInfo) -> str:
"""
Returns a human-readable string representation of the address.
Parameters
----------
ci: ConnectionInfo
The connection information object to represent the address of.
Returns
-------
str
String representation of the address.
"""
if ci.protocol == "pnp":
address = ci.address
elif ":" in ci.address[0]:
address = "[{}]:{}".format(*ci.address)
else:
address = "{}:{}".format(*ci.address)
return address
# ----------------------------------------------------------------------------
[docs]
def represent_connection(ci: ConnectionInfo) -> str:
"""
Returns a human-readable string representation of the connection.
Parameters
----------
ci: ConnectionInfo
The connection information object to represent the connection of.
Returns
-------
str
String representation of the connection.
"""
return "{} using {}".format(
represent_address(ci),
{
"pnp": "Qblox plug & play only (IP & name configuration only)",
"legacy": "legacy configuration manager (update only)",
"scpi": "SCPI",
}.get(ci.protocol, "?"),
)
# ----------------------------------------------------------------------------
[docs]
def represent_device(ci: ConnectionInfo) -> str:
"""
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
-------
str
String representation of the device.
"""
info = []
if ci.device.serial is not None:
info.append(f"serial {ci.device.serial}")
if ci.name is not None:
info.append(f"name {ci.name}")
if info:
info = f", with {' and '.join(info)}"
else:
info = ""
return f"{ci.device} at address {represent_address(ci)} ({'whole instrument' if ci.slot_index is None else f'only slot {ci.slot_index}'}){info}"
# ----------------------------------------------------------------------------
[docs]
def pprint_connection_info(
ci: ConnectionInfo, output: Callable[[str], None] = log.info
) -> None:
"""
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.
Returns
-------
"""
# Format address.
if ci.protocol == "pnp":
address = ci.address
port = PNP_PORT
else:
address, port = ci.address
# Format protocol.
protocol = "{}{}".format(
{
"pnp": "Qblox plug & play only (IP & name configuration only), via UDP broadcast port ",
"legacy": "legacy configuration manager (update only), via TCP port ",
"scpi": "SCPI, via TCP port ",
}.get(ci.protocol, "?"),
port,
)
# Format scope.
if ci.slot_index is None:
scope = "entire instrument"
elif ci.slot_index == 0:
scope = "only the cluster management module"
else:
scope = f"only the module in slot {ci.slot_index}"
# Format server version.
if ci.server_version is None:
server_version = "n/a"
else:
server_version = ".".join(map(str, ci.server_version))
# Format submodule model names.
submodule_models = ", ".join(
(model for model in ci.all_models if model != ci.device.model)
)
if not submodule_models:
submodule_models = "n/a"
# Print connection information.
output(f"Connecting to : {address}")
output(f"Via protocol : {protocol}")
output(f"Configuration scope : {scope}")
output(f"Server version : {server_version}")
output(f"Client version : {'.'.join(map(str, ci.client_version))}")
output("-------------------------:-------------------------")
output(f"Device type : {ci.device}")
output(f"Device name : {ci.name}")
output(f"Serial number : {ci.device.serial}")
output(f"IP configuration : {ci.ip_config}")
output(f"Submodule types : {submodule_models}")
for key, pretty in (
("sw", "Application"),
("fw", "FPGA firmware"),
("kmod", "Kernel module"),
("cfg_man", "Config. manager"),
):
if key in ci.device:
output(f"{pretty + ' version':<25}: {ci.device[key]}")
# ----------------------------------------------------------------------------
[docs]
def connection_info_to_json(ci: ConnectionInfo) -> dict:
"""
Converts a ConnectionInfo object to a JSON-serializable representation
thereof.
Parameters
----------
ci: ConnectionInfo
The connection information object to pretty-print.
Returns
-------
dict
A structure using only JSON-serializable types with all the information
of the ConnectionInfo object in it.
"""
d = ci._asdict()
d["device"] = d["device"].to_dict()
d["all_models"] = list(d["all_models"])
return d
# ----------------------------------------------------------------------------
[docs]
def probe_device(
identifier: Union[str, AddressInfo, ConnectionInfo], quiet: bool = False
) -> ConnectionInfo:
"""
Automatically detects how to manage the given device.
Parameters
----------
identifier: str
Instrument identifier. See :func:`~qblox_instruments.resolve()` for
more information.
quiet: bool
When set, don't log anything.
Returns
-------
ConnectionInfo
The detected connection and device information.
Raises
------
RuntimeError
if we failed to connect.
"""
# Fallthrough if input is already a resolved configuration structure.
if isinstance(identifier, ConnectionInfo):
return identifier
# Figure out our client version, taken from the generated SCPI class.
client_version = VERSION
# Figure out how to connect to the device with the given identifier.
info = resolve(identifier)
protocol = info.protocol
address = info.address
slot_index = info.slot_index
app_port = info.scpi_port
cfg_port = info.cfg_port
# Load default return values.
full_address = address
ip_config = "unknown"
server_version = None
device = None
all_models = set()
name = None
# Handle the case where we can only connect via plug & play.
if protocol == "pnp":
# Get device information via plug & play.
with PlugAndPlay() as p:
description = p.describe(identifier).get("description", {})
# Parse build information.
device = DeviceInfo.from_dict(description)
name = description.get("name", None)
all_models.add(device.model)
elif protocol == "ip":
# Preferentially connect to the application.
fall_back_to_cfg_man = False
# Try to connect to the application running on the device with a
# short timeout (since it's acceptable if we can't connect to it).
if not quiet:
log.info("Trying to connect to application (port %d)...", app_port)
info = None
try:
info = probe_port(address, app_port, client_version, 1.0)
except Exception as e:
fall_back_to_cfg_man = True
if not quiet:
log.info(
"Failed to connect to application (%s), "
"falling back to cfg_man.",
e,
)
if info is not None:
# We can connect to the application. Update device information
# from what we've learned from this.
protocol = "scpi"
full_address = (address, app_port)
server_version = info.version
device = info.device
all_models.add(device.model)
# Fall back anyway if we're only supposed to affect the module
# we're directly connected to, and not any of the submodules
# controlled by it.
if slot_index == CMM_SLOT_INDEX:
fall_back_to_cfg_man = True
if not quiet:
log.info(
"Application is responsive, but connecting to "
"configuration manager anyway, such that only the "
"management module is updated."
)
# Fall back anyway if the application doesn't support the
# configuration command set.
elif "legacy" in info.protocol:
fall_back_to_cfg_man = True
if not quiet:
log.info(
"Application is responsive, but doesn't support "
"configuration yet."
)
# Fall back to configuration manager if needed.
if fall_back_to_cfg_man:
if not quiet:
log.info(
"Trying to connect to configuration manager (port %d)...", cfg_port
)
info = None
try:
info = probe_port(address, cfg_port, client_version, 3.0)
except Exception as e:
fall_back_to_cfg_man = True
if not quiet:
log.info("Failed to connect to configuration manager (%s)", e)
raise RuntimeError(
f'Failed to connect to "{identifier}", determined to be at {address}.'
)
if info is not None:
# Update connection information.
protocol = "legacy" if "legacy" in info.protocol else "scpi"
full_address = (address, cfg_port)
server_version = info.version
if device is None:
device = info.device
else:
description = device.to_dict()
description.update(info.device.to_dict())
device = DeviceInfo.from_dict(description)
all_models.add(device.model)
else:
assert False
# Get some additional information if this is a fully-featured SCPI
# connection.
if protocol == "scpi":
with IpTransport(full_address[0], full_address[1], 3.0) as t:
cm = CfgMan(t)
# Read name from device.
name = cm.get_name()
# Read current IP configuration from device.
ip_config = cm.get_ip_config()
# Read module types.
module_types = cm._get_update_module_types()
if module_types != "not_applicable":
all_models.update(module_types.split(","))
# Warn if trying to configure an entire cluster when the CMM is not yet
# capable of doing that.
if protocol == "legacy" and device.model == "cluster_mm" and slot_index is None:
if not quiet:
log.warn(
"The current version of the software running on the "
"connected cluster management module (CMM) cannot "
"automatically update or roll back the other modules in the "
"cluster. To do that, CMM will need to be updated first. So, "
"in order to update the entire cluster, you will need to run "
"the updater twice."
)
slot_index = CMM_SLOT_INDEX
# Warn if the user is trying to configure only the cluster management
# module of a cluster, when the device we're connecting to is not a
# cluster management module.
if slot_index == CMM_SLOT_INDEX and device.model != "cluster_mm":
if not quiet:
log.warn(
"Scope was restricted to the cluster management module, but "
"the device we're connecting to is not a cluster."
)
slot_index = None
# Add the module suffix back onto the identifier.
if slot_index is not None:
identifier = f"{identifier}/{slot_index}"
# Build and return connection information structure.
return ConnectionInfo(
identifier,
protocol,
full_address,
slot_index,
ip_config,
server_version,
client_version,
device,
name,
all_models,
)
# ----------------------------------------------------------------------------
[docs]
def get_device_info(identifier: Union[str, AddressInfo, ConnectionInfo]) -> DeviceInfo:
"""
Fetches a complete :class:`~qblox_instruments.DeviceInfo` structure for
the given device.
Parameters
----------
identifier: Union[str, AddressInfo, ConnectionInfo]
Instrument identifier. See :func:`~qblox_instruments.resolve()` for
more information.
Returns
-------
DeviceInfo
The device information.
Raises
------
RuntimeError
if we failed to connect.
"""
return probe_device(identifier, quiet=True).device
