Metadata-Version: 2.4
Name: instrutech-gauges
Version: 0.1.2
Summary: Python drivers for InstruTech gauges over serial or TCP serial gateways
Keywords: instrutech,vacuum,gauge,serial,rs232,rs485
Author: Olivier Grasdijk
Author-email: Olivier Grasdijk <o.grasdijk@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pyserial>=3.5
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/ograsdijk/instrutech-gauges
Project-URL: Repository, https://github.com/ograsdijk/instrutech-gauges
Project-URL: Issues, https://github.com/ograsdijk/instrutech-gauges/issues
Description-Content-Type: text/markdown

# instrutech-gauges

Python drivers for InstruTech gauges over serial or TCP serial gateways.

## Install

```bash
uv add instrutech-gauges
```

Or for local development:

```bash
uv sync
```

## Available drivers

- `VGC301`
- `HornetIGM402`
- Public base class for custom devices: `InstruTechAsciiGauge`

## Quick start (VGC301)

```python
from instrutech_gauges import SerialTransport, VGC301

t = SerialTransport(port="/dev/ttyUSB0", baudrate=19200, timeout_s=0.3)
g = VGC301(t, address=1)

with g:
    print(g.read_sw_version())
    print(g.read_pressure_torr())
    g.set_trip_point(1, "on_below", 4.00e2)
    print(g.read_trip_point(1, "on_below"))
```

## Quick start (Hornet IGM402)

```python
from instrutech_gauges import HornetIGM402, SerialTransport

t = SerialTransport(port="/dev/ttyUSB0", baudrate=19200, timeout_s=0.3)
g = HornetIGM402(t, address=1)

with g:
    print(g.read_sw_version())
    print(g.read_system_pressure_torr())
    print(g.read_pressure_unit())
```

Firmware notes for `HornetIGM402`:

- `SES` emission setting responses like `0.1MA_EM` / `4.0MA_EM` are parsed.
- `RU` accepts long unit tokens (`TORR`, `MBAR`, `PASCAL`).
- Optional command families (`RU/SU`, `RDIG*`) raise
  `InstruTechUnsupportedCommandError` on firmware that returns `SYNTX ER`.
- Socket transport defaults to `\r` command termination.

## Without context manager (`with`)

Use explicit `open()` / `close()` with `try/finally`:

```python
from instrutech_gauges import SerialTransport, VGC301

t = SerialTransport(port="/dev/ttyUSB0", baudrate=19200, timeout_s=0.3)
g = VGC301(t, address=1)

g.open(probe=True)
try:
    print(g.read_sw_version())
    print(g.read_pressure_torr())
finally:
    g.close()
```

```python
from instrutech_gauges import HornetIGM402, SerialTransport

t = SerialTransport(port="/dev/ttyUSB0", baudrate=19200, timeout_s=0.3)
g = HornetIGM402(t, address=1)

g.open(probe=True)
try:
    print(g.read_sw_version())
    print(g.read_system_pressure_torr())
finally:
    g.close()
```

## Public base class

`InstruTechAsciiGauge` exposes shared protocol and transport helpers for building new drivers:

- framing/parsing (`#xx...<CR>`, `*xx...<CR>`)
- `query()` / `query_float()` / `command_prog_ok()`
- serial reconfiguration (`set_baud`, `set_parity`, `set_serial_comm`)
- common Mini-Convectron-style commands (`VER`, `RD`, `TS`, `TZ`, `SL/SH`, `RL/RH`, `FAC`, `RST`)

Minimal custom driver:

```python
from instrutech_gauges import InstruTechAsciiGauge

class MyGauge(InstruTechAsciiGauge):
    def read_custom_value(self) -> float:
        return self.query_float("RDCUSTOM")
```

## Transport

- `SerialTransport`: local serial via `pyserial`
- `SocketTransport`: TCP serial gateways (raw TCP)

`SocketTransport` defaults to CR (`\r`) command termination. If your gateway expects
CRLF, override it:

```python
from instrutech_gauges import SocketTransport

t = SocketTransport("192.168.1.50", 4001, timeout_s=1.0, write_terminator=b"\r\n")
```

Runtime serial reconfiguration (`set_baud`, `set_parity`) is supported only with `SerialTransport`.

## VGC301 serial notes

Per the VGC301 manual, `SB*` / `SP*` / `SA*` / `FAC` require `RST` before they take effect.

- `VGC301.set_baud(...)` defaults to `reset_after=True`
- `VGC301.set_parity(...)` defaults to `reset_after=True`
- For ODD/EVEN parity, data bits default to 7; for NO parity, data bits default to 8

## Error handling

Typical exceptions:

- `InstruTechTimeoutError`
- `InstruTechProtocolError`
- `InstruTechDeviceError`
- `InstruTechUnsupportedTransportOperationError`

## Release flow

- CI runs on every push and PR (`.github/workflows/ci.yml`).
- PyPI publish runs only on tags that start with `v` (`.github/workflows/publish.yml`).
- Publish is blocked unless tag version matches `pyproject.toml` version exactly.

Example release:

```bash
git tag v0.1.1
git push origin v0.1.1
```

Configure PyPI Trusted Publisher for this repository so the publish workflow can upload without storing an API token.
