Metadata-Version: 2.1
Name: hpspmplusstudio
Version: 1.0.9
Summary: Python API for controlling and monitoring hpSPM+ Studio (NanoMagnetics Instruments)
Author: NanoMagnetics Instruments
Author-email: nmi.swteam@nano.com.tr
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: pillow>=9.0
Requires-Dist: tqdm>=4.60
Requires-Dist: PyVISA>=1.12
Provides-Extra: andor
Requires-Dist: pylablib; extra == "andor"

**hpSPM+ Studio Library Description**

The **hpSPM+ Studio Python Library** is a powerful API designed for seamless interaction with **hpSPM+ systems**, providing comprehensive tools for system customization, real-time monitoring, and data management. Its modular structure allows easy integration into scientific and industrial workflows.

Key features include:

- **Device Control**:
  - Complete control over scanning processes, voltage configurations, and offset adjustments.
  - Optimizes system performance with automatic calibration and setup features.
- **Real-Time System Monitoring**:
  - Provides real-time access to essential metrics like system status and scan progress.
  - Delivers detailed feedback on scanning status, voltage levels, and system activities.
- **Data Management**:
  - Records, organizes, and analyzes scanned images and system readings.
  - Offers the ability to manage image containers effectively.
- **Customizable Solutions**:
  - Configures scanning parameters and other settings to meet experimental or industrial requirements.
  - Its modular design enhances system scalability.

This library is an ideal tool for automating workflows, optimizing device performance, and developing custom applications.

# Prerequisites

- **Operating System:** Windows 10 or later.
- **Python Version:** Python versions 3.9 to 3.12. Download Python from python.org.
- **hpSPM+ Studio Software:** The hpSPM+ Studio software must be installed, and its API feature should be activated.
- **Network Access:** The hpSPM+ device must be accessible via its designated IP address and port.
- **pip Package Manager:** The Python pip package manager is required to install the library.
- **Dependencies:** All required dependencies are installed automatically during the library setup.
- **Development Environment (Recommended):** Using Visual Studio Code is recommended for writing, debugging, and running Python scripts.

**Note:** Ensure your Python environment is properly configured before proceeding with the installation.

# Installation and Upgrading

- **To Install the hpSPM+ Python Library:**
  - Open a Windows Command Prompt or terminal with Python installed.
  - Enter the following command:

pip install hpspmplusstudio

- **To Upgrade to the Latest Version of the hpSPM+ Library:**
  - Use the following command:

pip install hpspmplusstudio -U

**Note:** Ensure your Python environment meets all the prerequisites listed before proceeding with the installation or upgrade.

# Running the Examples

The **hpSPM+ Studio Python Library** provides comprehensive documentation, sample scripts, and application templates to help users get started quickly. These resources are organized into separate directories such as Docs and Samples within the package.

To locate these files on your system, follow these steps:

1. Open a terminal or command prompt with Python installed.
2. Enter the following commands to access the library's help feature:

python

\>>> import hpSPMPlusStudio

\>>> hpSPMPlusStudio.help()

1. The output will display the exact paths to the documentation (Docs) and example scripts (Samples). For instance:
    1. **Docs**: Contains the PDF manual and library overview files.
    2. **Samples**: Includes subfolders like Basics and Experiments with practical examples.

We recommend using **Visual Studio Code** or a similar IDE for writing, debugging, and running Python scripts. You can explore the examples in the Samples folder to better understand how to interact with the hpSPM+ API and customize it for your needs.

# Connection and Logging

- Every request uses a timeout of 5 s (connect) / 60 s (read). It can be changed per endpoint, e.g. `NMIEndpoint("192.168.10.110", 9024, timeout=(5, 120))`.
- Failed requests and server error messages are printed to the console and written to the `hpSPMPlusStudio` logger, and the method returns `None`.
- The reason of the last failure is kept in `Endpoint.last_error` (`{"command", "status_code", "message"}`; `None` after a successful request).
- Console printing can be turned off with `hpSPMPlusStudio.set_verbose(False)`; the messages are still logged.
- The library does not write a log file by default. To write the library logs to a file:

\>>> import hpSPMPlusStudio

\>>> hpSPMPlusStudio.enable_file_logging("logFile_API.log")

# Reading Values

Some flags come from the server as JSON booleans and others as the strings `"True"`/`"False"` (for example `SCAN().Get_IsScanning()`, `STATUS().Get_DashboardStatus()`, `PID().Get_PID()`). In Python `bool("False")` is `True`, so use the helpers:

\>>> from hpSPMPlusStudio import to_bool, to_float

\>>> to_bool(Device.SCAN().Get_IsScanning()["IsScanning"])

- `to_bool(value)`: `"True"/"False"`, `"1"/"0"` and booleans.
- `to_float(value)`: numbers, decimal-comma strings (`"1,25"`) and `"NaN"`/`"Infinity"`.
- `get_first(response, "NewKey", "OldKey")`: first key that exists in a response.

# Modules

| Accessor | Module | Notes |
|---|---|---|
| `STATUS()` | APP | System state, dashboard, `DeviceInformations()` |
| `SYSTEMREADINGS()` | SystemReadings | Live signals; `Get_SystemReadingsWithTimestamp()` adds the frame time |
| `SCAN()` | Scan | Scan geometry, speed, start/stop, save folder/name, scan channel selection |
| `SCANNEDIMAGES()` | ScannedImages | Image containers, image data (any frame), `Save_Container()` |
| `OPTIONS()` | Options | SPM type, AFM mode, scanner type, XY/Z scale |
| `XYOFFSET()` | XYOffset | XY offset (ramped or direct), GUI offset updater |
| `PID()` | PID | P/I/D, set point, enable, polarity |
| `TIPFEEDBACK()` | TipFeedback | **New in 1.0.9.** Z feedback state: FeedbackOn / FeedbackOff / Standby |
| `APPROACH()` | Approach | Coarse motors, `Get_MotorState()`, `Get_LandHistory()` |
| `AUTOTUNE()` | AutoTune | Frequency sweep, excitation, Null Phase, Q factor |
| `IVCURVE()` | IVCurve | **New in 1.0.9.** IV spectroscopy (bias sweep) |
| `PHOTODIODE()` | PhotoDiode | Photodiode signals, laser power/RF, laser on/off |
| `VBIAS()` | VBias | Bias DC/AC, /500 divider, polarity, measured bias |
| `HALLCARD()` | HallCard | Hall probe and coil driver |
| `FIBERCARD()` | FiberCard | Fiber interferometer card, quadlock |
| `ADJUSTFIBER()` | AdjustFiber | Find Quadrature |
| `WINDOWCONTROLLER()` | WindowControl | GUI tool windows |
| `DIO()`, `SPAREDAC()` | DIO, SpareDac | **NMISPMStudio only.** hpSPM+ has no such routes; calls return `None` |

Laser: `PHOTODIODE().Set_LaserOn()` / `Set_LaserOff()` switch the laser. `Set_LaserEnable()` / `Set_LaserDisable()` only unlock or lock the GUI "Laser" checkbox.

Units: XY lengths (offsets, image size, `CustomScanner` sizes) are in the GUI XY scale unit (`OPTIONS().Get_XYScale()`). IV curve bias values are in mV. `SCAN().Set_ScanTemperature()` is the piezo calibration temperature in Kelvin.

# Changelog

## 1.0.9

Commands marked *(server)* need hpSPM software with the October 2026 API update; older software answers "Command not found" / "Route not found" and the method returns `None`.

- New `IVCURVE()` controller (all IV curve commands; `Get_ChartData(channel)` returns `(keys, values)`).
- New `TIPFEEDBACK()` controller *(server)*.
- New commands *(server)*: Approach `Get_MotorState`, `Get_LandHistory`; Scan `Get/Set_ImageDirectory`, `Get/Set_ImageName`, `Get_ScanSpeedTypeList`, `Get/Set_ScanSpeedType`, `Get_ScanChannels`, `Set_ScanChannelSelected`, `Set_ScanChannels`; ScannedImages frame index, `Get_FrameCount`, `Save_Container`; VBias `Get_BiasVoltRead`, `Get_MaxACAmplitude`, `Get_IsSwForcedDC`, `Get/Set_DividerEnabled`, `Get/Set_Polarity`; AutoTune `Get/Set_ExcitationSetMode`, `Get_MaxExcitation`, `Get_ExcitationRead`, `Get/Set_TuningAutoNullPhase`, `Get_QFactor`, `Get_FreeRms`, `Get/Set_AutoRetract`, `NullPhase`; FiberCard `Get_FiberPZTVoltageRead`, `Get_Vpd`, `Get_FiberVoltageLimits`, `Get_FiberCardMode`; AdjustFiber `Get/Set_FindQuadraturePztDelay`, `Get/Set_FindQuadratureMiddleDelay`; IVCurve `Get/Set_FirstPointDelay`, `Get/Set_IsFreezeFeedback`, channels `Vpd`, `FN`, `FN10`; PhotoDiode `Set_LaserOn`, `Set_LaserOff`, `Get_IsLaserChangeEnabled`; SystemReadings `Get_SystemReadingsWithTimestamp`; XYOffset `Get_IsGuiOffsetUpdaterRunning`.
- `STATUS().DeviceInformations()`; `HALLCARD().Get_HallAmplitudeBandwidth()` alias; HallCard bandwidth accepts 0.01 / 0.1 kHz; `ADJUSTFIBER().Set_SlopeMode(direction, point)`.
- Enum values are checked before sending (Approach distance/speed type, AutoTune frequency slope, AdjustFiber slope mode, IV type/channel, tip feedback state).
- Request layer: `Endpoint.last_error`, `set_verbose()`, HTTP status and plain-text errors are reported, a JSON `null` body no longer raises, NaN/inf values are not sent, `NMIEndpoint.close()` / `with NMIEndpoint(...)`, `NMIDevice` applies the timeout of a new endpoint for the same address.
- `CustomScanner`: ramps to the first pixel before stopping the GUI offset updater, restores the updater and the original offset in all cases, checks the offset limits and every direct move, `origin="center"`, NaN padding for failed external devices.
- Samples fixed (`to_bool` for `IsScanning`, units, laser lock vs. on/off, slope mode, restoring PID values); new `IVCurve.py`, `TipFeedback.py`, `ScanCustom.py`.
