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: Union[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