sqidevice 2.0.0__tar.gz

sqidevice-2.0.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

sqidevice-2.0.0/.gitlab-ci.yml

@@ -0,0 +1,12 @@
+stages:
+ - test
+
+test-job:
+  stage: test
+  before_script:
+    - python -m pip install -U ruff
+  script:
+    - python -m ruff check
+    - python -m pytest
+  tags:
+    - mogrunner

sqidevice-2.0.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v2.3.0
+  hooks:
+    - id: check-yaml
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.12.0
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format
+- repo: local
+  hooks:
+    - id: pytest-check
+      name: pytest-check
+      entry: pytest
+      language: system
+      pass_filenames: false
+      always_run: true

sqidevice-2.0.0/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2017 - present, Santec Australia Pty Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

sqidevice-2.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: sqidevice
+Version: 2.0.0
+Summary: Python interface for communicating with Santec Quantum Instrument devices
+Author: Santec Australia
+License: MIT
+License-File: LICENSE.txt
+Keywords: ethernet,instrument,quantum,santec,usb
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Instrument Drivers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Requires-Dist: pyserial>=3.0
+Description-Content-Type: text/markdown
+
+# SQIDevice: Simple interface to Santec Quantum Instruments
+
+The `SQIDevice` class provides a simple interface for interacting with Santec Quantum Instruments over
+a USB or ETH connection.
+
+It handles end-of-message termination, concatenating multi-component responses, and converts error messages into exceptions to simplify error handling in the application.
+
+Helper functions are provided for common operations, such as `ask_val()` for querying a numerical value and converting SI units, and `ask_list()` to transform comma-separated values into a `list`.
+
+
+## Overview
+
+The `SQIDevice` class is instantiated with a string defining the connection instance, for example:
+```
+# TCP connection by specifying IP address and optionally server port
+SQIDevice("10.1.1.122")
+SQIDevice("10.1.1.122:7802")
+SQIDevice("10.1.1.122", port=7802)
+
+# USB connection via virtual COM port
+SQIDevice("COM3")
+SQIDevice("USB", port=3)
+```
+
+The primary functions for communicating with the device are:
+* `ask(query)`: Send the provided `query` string and return the response as a string.
+        Intended as the main mechanism for _reading_ values from the device.
+        If `query` is bytes, the return value is also bytes.
+* `ask_val(query)`: Calls `ask(query)` and performs type conversion on the response string; to `float` by default.
+        Also performs simple SI-units conversion of the response, when units are provided.
+        Recommended for querying measured values from the device, instead of type-casting the response string directly.
+* `ask_dict(query)`: Calls `ask(query)` and parses the response string into a python dictionary.
+        Intended for parsing compound responses such as `VER` and `REPORT`.
+        Does not perform type conversion of the values.
+* `ask_list(query)`: Calls `ask(query)` and parses the response as a comma-separated list of values.
+        Optionally performs unit conversion and type conversion.
+* `cmd(command)`: Send the provided command string to the device and wait for a response.
+        Commands are different from queries in that they induce an action and hence are expected to respond with an `OK` string.
+        Intended to be used when _writing_ values to the device.
+        Failing to respond in this way raises a `DeviceError`.
+* `reconnect()`: Close the connection (if applicable) and reconnect with the same parameters.
+        Recommended for handling disconnection or reboot events.
+
+
+The queries and commands are product-specific, and can be found in the appropriate Appendix of the relevant product manual.
+
+
+
+## Properties
+The `INFO` query is common across compatible devices to help identify the product at a glance.
+The `SQIDevice` parses this query at connection and stores the results as a `dict` which can be accessed directly by indexing the device instance via `__getitem__()`.
+
+The dictionary contains at least the following keys:
+- `type`: Product name string (e.g. "DDLC" or "FZW").
+- `rev`: Mainboard PCB revision, to help identify firmware compatibility.
+- `ver`: Primary version numbers for the UC (and FPGA if applicable). See also the `VER` query for additional information.
+- `serial`: Serial number of the unit.
+- `name`: User-defined name for the unit, as set with the `DEVNAME` command, or the serial number when a custom name is not set.
+- `iap`: Identifies that the devices is in firmware-update (IAP) mode.
+
+
+## Error handling
+The command and query functions of the `SQIDevice` class raise exceptions to handle error scenarios, that should be caught at the application level.
+
+### DeviceError
+A response was successfully received from the device, but that response is an error message.
+This raises an instance of `DeviceError` containing both the request that failed and the response error message.
+
+### USBError
+Particularly on the Windows(tm) operating system, the error messages raised by `pyserial` are often unintuitive and it is unclear how to resolve them.
+
+The `USBError` class is a subclass of `OSError` that translates the most common error messages into a clearer form.
+
+### TimeoutError
+Raised if no response was received, or an incomplete response was received before the timeout period elapsed.
+
+### OSError
+Typically any error at the transport level will result in a subclass of `OSError` being raised by the underlying `socket` or `serial` class instances.
+Usually this indicates that the device has been disconnected, rebooted, or powered off, and needs to be reconnected.
+
+Examples include `TimeoutError` and `USBError`.
+
+### AssertionError
+If an attempt is made to communicate with the device after closing the connection, it will cause `AssertionError` to be raised.

sqidevice-2.0.0/README.md

@@ -0,0 +1,84 @@
+# SQIDevice: Simple interface to Santec Quantum Instruments
+
+The `SQIDevice` class provides a simple interface for interacting with Santec Quantum Instruments over
+a USB or ETH connection.
+
+It handles end-of-message termination, concatenating multi-component responses, and converts error messages into exceptions to simplify error handling in the application.
+
+Helper functions are provided for common operations, such as `ask_val()` for querying a numerical value and converting SI units, and `ask_list()` to transform comma-separated values into a `list`.
+
+
+## Overview
+
+The `SQIDevice` class is instantiated with a string defining the connection instance, for example:
+```
+# TCP connection by specifying IP address and optionally server port
+SQIDevice("10.1.1.122")
+SQIDevice("10.1.1.122:7802")
+SQIDevice("10.1.1.122", port=7802)
+
+# USB connection via virtual COM port
+SQIDevice("COM3")
+SQIDevice("USB", port=3)
+```
+
+The primary functions for communicating with the device are:
+* `ask(query)`: Send the provided `query` string and return the response as a string.
+        Intended as the main mechanism for _reading_ values from the device.
+        If `query` is bytes, the return value is also bytes.
+* `ask_val(query)`: Calls `ask(query)` and performs type conversion on the response string; to `float` by default.
+        Also performs simple SI-units conversion of the response, when units are provided.
+        Recommended for querying measured values from the device, instead of type-casting the response string directly.
+* `ask_dict(query)`: Calls `ask(query)` and parses the response string into a python dictionary.
+        Intended for parsing compound responses such as `VER` and `REPORT`.
+        Does not perform type conversion of the values.
+* `ask_list(query)`: Calls `ask(query)` and parses the response as a comma-separated list of values.
+        Optionally performs unit conversion and type conversion.
+* `cmd(command)`: Send the provided command string to the device and wait for a response.
+        Commands are different from queries in that they induce an action and hence are expected to respond with an `OK` string.
+        Intended to be used when _writing_ values to the device.
+        Failing to respond in this way raises a `DeviceError`.
+* `reconnect()`: Close the connection (if applicable) and reconnect with the same parameters.
+        Recommended for handling disconnection or reboot events.
+
+
+The queries and commands are product-specific, and can be found in the appropriate Appendix of the relevant product manual.
+
+
+
+## Properties
+The `INFO` query is common across compatible devices to help identify the product at a glance.
+The `SQIDevice` parses this query at connection and stores the results as a `dict` which can be accessed directly by indexing the device instance via `__getitem__()`.
+
+The dictionary contains at least the following keys:
+- `type`: Product name string (e.g. "DDLC" or "FZW").
+- `rev`: Mainboard PCB revision, to help identify firmware compatibility.
+- `ver`: Primary version numbers for the UC (and FPGA if applicable). See also the `VER` query for additional information.
+- `serial`: Serial number of the unit.
+- `name`: User-defined name for the unit, as set with the `DEVNAME` command, or the serial number when a custom name is not set.
+- `iap`: Identifies that the devices is in firmware-update (IAP) mode.
+
+
+## Error handling
+The command and query functions of the `SQIDevice` class raise exceptions to handle error scenarios, that should be caught at the application level.
+
+### DeviceError
+A response was successfully received from the device, but that response is an error message.
+This raises an instance of `DeviceError` containing both the request that failed and the response error message.
+
+### USBError
+Particularly on the Windows(tm) operating system, the error messages raised by `pyserial` are often unintuitive and it is unclear how to resolve them.
+
+The `USBError` class is a subclass of `OSError` that translates the most common error messages into a clearer form.
+
+### TimeoutError
+Raised if no response was received, or an incomplete response was received before the timeout period elapsed.
+
+### OSError
+Typically any error at the transport level will result in a subclass of `OSError` being raised by the underlying `socket` or `serial` class instances.
+Usually this indicates that the device has been disconnected, rebooted, or powered off, and needs to be reconnected.
+
+Examples include `TimeoutError` and `USBError`.
+
+### AssertionError
+If an attempt is made to communicate with the device after closing the connection, it will cause `AssertionError` to be raised.

sqidevice-2.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "sqidevice"
+version = "2.0.0"
+description = "Python interface for communicating with Santec Quantum Instrument devices"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Santec Australia" }]
+keywords = ["santec", "quantum", "instrument", "usb", "ethernet"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Instrument Drivers",
+]
+dependencies = [
+    "pyserial>=3.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sqidevice"]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "SIM", "PL"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+

sqidevice-2.0.0/sqidevice/__init__.py

@@ -0,0 +1,18 @@
+# Public device class
+from .sqidevice import SQIDevice, CRLF
+
+# Error handling classes
+from .sqidevice import DeviceError, USBError
+
+# Helper functions
+from .sqidevice import convert_measurement, load_script
+
+# Define * imports
+__all__ = [
+    "SQIDevice",
+    "CRLF",
+    "DeviceError",
+    "USBError",
+    "convert_measurement",
+    "load_script",
+]