Metadata-Version: 2.4
Name: mmcb-rs232-avt
Version: 1.2.0
Summary: ATLAS ITK Pixels Multi-Module Cycling Box environmental monitoring/control (RS232)
Home-page: https://gitlab.ph.liv.ac.uk/avt/atlas-itk-pmmcb-rs232
Author: Alan Taylor
Author-email: avt@hep.ph.liv.ac.uk
Maintainer: Alan Taylor
Maintainer-email: avt@hep.ph.liv.ac.uk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: zmq
Requires-Dist: pyserial==3.4.*
Requires-Dist: tables
Requires-Dist: yoctopuce
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Serial port handling for the ATLAS ITK pixels multi-module cycling box

[![PyPI version](https://badge.fury.io/py/mmcb-rs232-avt.svg)](https://badge.fury.io/py/mmcb-rs232-avt)

![image](https://hep.ph.liv.ac.uk/~avt/pypi/logo.png)

*Particle Physics, University of Liverpool, UK*

## Features

This repository provides command line tools to monitor and control equipment in the *ATLAS ITK pixels multi-module cycling box* test setup. It is used in the test setups for a number of other projects. Interactions with these instruments are performed via FTDI USB to RS232 adaptors.

### Main commands

|Command|Function|
|:---:|:---:|
|[dmm](packaging/src/mmcbrs232/dmm.py)|Reads voltage/current values from the Keithley DMM6500 6.5 digit multimeter.|
|[iv](packaging/src/mmcbrs232/iv.py)|Configurable script to measure IV/IT curves using the Keithley 2410/2614b (RS232). It can operate multiple PSUs concurrently, embed environmental data into log files, and can be easily used in shell scripts to automate tasks such as HV-cycling.|
|[psuset](packaging/src/mmcbrs232/psuset.py)|Sets current/voltage parameters for power supplies (RS232: Keithley 2410/2614b, Hameg HMP4040). Works in both constant voltage and constant current modes.|
|[ult80](packaging/src/mmcbrs232/ult80.py)|Queries and/or sets parameters for the ULT80 chiller (RS232).|

### ZeroMQ serial port server

The following commands use the ZeroMQ serial port server to interact with instrumentation connected via FTDI USB to RS232 adaptors, rather than interacting with the devices directly as the commands above do.

|Command|Function|
|:---:|:---:|
|[rs232_zmq_server](packaging/src/mmcbrs232/broker_and_workers.py)|Provides shared, parallel access to RS232 instruments. Concurrent requests to the same serial port are serialised by order of arrival since interactions with a given serial port is managed by a single thread specific to that serial port.|
|[zpsustat](packaging/src/mmcbrs232/zpsustat.py)|Replacement for `psustat`. This supports requests for information on specified, individual PSU channels only. This command does not (yet) support use without arguments, as `psustat` does to display status of all PSUs.|
|[zpsuset](packaging/src/mmcbrs232/zpsuset.py)|Drop-in replacement for `psuset`.|
|[zult80](packaging/src/mmcbrs232/zult80.py)|Drop-in replacement for `ult80`.|

### Support commands

|Command|Function|
|:---:|:---:|
|[detect](packaging/src/mmcbrs232/detect.py)|Detects equipment attached by RS232, writes a cache file containing identified equipment to `~/.cache.json`. Run *once* after the RS232 configuration has changed.|
|[mmcb_cache](packaging/src/mmcbrs232/mmcb_cache.py)|Displays the contents of the cache file (`~/.cache.json`) in human-readable form.|
|[liveplot](packaging/src/mmcbrs232/liveplot.py)|Companion to `iv`. Displays IV plot in real-time in a graphical window.|
|[psustat](packaging/src/mmcbrs232/psustat.py)|Provides a single-shot view of the status of all power supply channels (RS232: Keithley 2410/2614b, Hameg HMP4040).|

## History

The files in this repository were originally part of the [atlas-mmcb-avt](https://gitlab.ph.liv.ac.uk/avt/atlas-itk-pmmcb/) repository, which used to handle monitoring and control of equipment attached via I2C, GPIO and serial port. To support the serial port interaction being run on a conventional Intel DAQ computer, these functions were split into two packages. All RS232 serial port interaction code is now contained in this package.

The Raspberry Pi specific aspects (I2C environmenal monitoring and Peltier device polarity switching via GPIO) remain in the [atlas-mmcb-avt](https://gitlab.ph.liv.ac.uk/avt/atlas-itk-pmmcb/) repository, which no longer contains any serial port capability.

## Documentation

For project documentation, see the [wiki](https://gitlab.ph.liv.ac.uk/avt/atlas-itk-pmmcb/-/wikis/home), or each command's in-built help, e.g. `psustat --help`.


## Installation

This software is publically available and may be obtained from [The Python Package Index](https://pypi.org/project/mmcb-avt/).

This repository provides also a wheel (`.whl`) file that is installable with [pip](https://packaging.python.org/en/latest/key_projects/#pip). See the [packaging](packaging) directory for installation instructions.


## Support

Support requests to [avt@hep.ph.liv.ac.uk](mailto:avt@hep.ph.liv.ac.uk) or via the [Issue Tracker](https://gitlab.ph.liv.ac.uk/avt/atlas-itk-pmmcb/-/issues).


## Installation notes

### Yoctopuce sensors

In addition to the dependencies installed with pip, testing ATLAS sensors on the old probestation (for convenience) will also require the [Yoctopuce Command line API](https://www.yoctopuce.com/EN/libraries.php). Please install the correct version for your architecture - this will provide commands such as `YTemperature` and `YHumidity` to monitor the probestation interior state from the command line.

Install the archive (e.g. `Cmdlines.linux_arm.70284.zip`) into `~/dev` and then set the path to include `~/dev/Cmdlines/Binaries/linux/aarch64`, e.g. `PATH=$PATH:~/dev/Cmdlines/Binaries/linux/aarch64`.

## ZeroMQ serial port server

This is based on the ZeroMQ Majordomo pattern, and has a separate thread managing each serial port.

```console
(base) [pixeldaq@atldaq1 ~]$ rs232_zmq_server -h
usage: rs232_zmq_server [-h] [-v] [-n]

ZeroMQ server (broker and workers) for the ATLAS Pixels multi-module cycling box serial port devices. This server manages
concurrent access to serial port resources for all attached clients. Commands line scripts emulated are psuset, psustat
and ult80. WARNING: ANY attached client has the authority to change ANY power supply or chiller parameter at ANY time.
Clients (PID control loops) running concurrently must ensure that they only modify their own resources, and not those of
other clients.

options:
  -h, --help     show this help message and exit
  -v, --verbose  Enable logging.
  -n, --nolock   Disable the use of the global rs232 lock. For safety this script will use the global rs232 lock by
                 default. This lock is a coarse measure that should prevent concurrent serial port access, even to
                 different ports, by this server and other command line scripts that may access serial port resources.
                 When running multiple concurrent asynchronous PID control scripts, using -n allows optimal sharing of
                 serial port resources between those scripts.
```

If you want the best performance from PID scripts, start the server with `-n`. If you need to use command line utilities (`psuset`, `psustat`, etc.) in parallel with PID scripts, then omit the `-n`.

### Start

```console
(base) [pixeldaq@atldaq1 ~]$ nohup rs232_zmq_server </dev/null >/dev/null 2>&1 &
(base) [pixeldaq@atldaq1 ~]$ disown
```

### Stop

```console
(base) [pixeldaq@atldaq1 ~]$ ps -ef | grep rs232_zmq_server
pixeldaq 18079 17527  0 12:00 pts/16   00:00:12 /usr/local/bin/python3 /home/pixeldaq/.local/bin/rs232_zmq_server
pixeldaq 26239 17527  0 12:51 pts/16   00:00:00 grep --color=auto rs232_zmq_server
(base) [pixeldaq@atldaq1 ~]$ kill 18079
```

### Test

```console
(base) [pixeldaq@atldaq1 ~]$ pip show mmcb-rs232-avt
WARNING: Ignoring invalid distribution ~ip (/home/pixeldaq/miniconda3/lib/python3.13/site-packages)
Name: mmcb-rs232-avt
Version: 1.1.28
Summary: ATLAS ITK Pixels Multi-Module Cycling Box environmental monitoring/control (RS232)
Home-page: https://gitlab.ph.liv.ac.uk/avt/atlas-itk-pmmcb-rs232
Author: Alan Taylor
Author-email: avt@hep.ph.liv.ac.uk
License:
Location: /home/pixeldaq/miniconda3/lib/python3.13/site-packages
Requires: matplotlib, numpy, pandas, pyserial, tables, yoctopuce, zmq
Required-by:

(base) [pixeldaq@atldaq1 ~]$ python
Python 3.13.2 | packaged by Anaconda, Inc. | (main, Feb  6 2025, 18:56:02) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from mmcbrs232 import mdclientlib
>>> mdclientlib.__version__
'1.1.28'
>>> mdc = mdclientlib.Rs232()
>>> mdc.
mdc.channels           mdc.get_pt_i(          mdc.get_ult80_temps()  mdc.psu_set(           mdc.psus
mdc.client             mdc.get_pt_v(          mdc.ports              mdc.psu_unset(         mdc.settings
>>> mdc.get_ult80_temps()
(23.0, 23.0)
>>> mdc.get_pt_v(103877, 2)
0.3
```

### Latency for common operations

```python
(base) [pixeldaq@atldaq1 ~]$ ipython
Python 3.13.2 | packaged by Anaconda, Inc. | (main, Feb  6 2025, 18:56:02) [GCC 11.2.0]
Type 'copyright', 'credits' or 'license' for more information
IPython 9.6.0 -- An enhanced Interactive Python. Type '?' for help.
Tip: You can use LaTeX or Unicode completion, `\alpha<tab>` will insert the α symbol.

In [1]: from mmcbrs232 import mdclientlib

In [2]: mdc = mdclientlib.Rs232()

In [3]: %timeit mdc.get_ult80_temps()
63.9 ms ± 26.4 μs per loop (mean ± std. dev. of 7 runs, 10 loops each)

In [4]: %timeit mdc.get_pt_v(103877, 2)
204 ms ± 8.58 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

In [5]: %timeit mdc.psu_set(103877, 2, 0.3, 4.95)
1.12 s ± 4.58 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

In [6]: %timeit mdc.psu_unset(103877, 2, 0.3, 4.95)
1.12 s ± 7.78 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
```
