Metadata-Version: 2.4
Name: coincellhell
Version: 0.1.0
Summary: Python bindings for the libcoincellhell library
Author: Carl Philipp Klemm
License-Expression: LGPL-2.0-or-later
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: libusb-package
Dynamic: author
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# libcoincellhellpy

**Python bindings for the `libcoincellhell` C library**

`libcoincellhellpy` provides a thin, high‑level wrapper around the native library
`libcoincellhell` that controls CoinCellHell devices with their four peltier
heaters and four coin cell channels. The functionality is implemented in C++
using pybind11.

---

## Installation

The package can be built and installed from source using the standard Python
build workflow:

```bash
# Fetch the libcoincellhell submodule
git submodule update --init

# Build and install the package
pip install -e .
```

To build against an already installed `libcoincellhell` instead of the submodule,
hand the CMake variables through scikit-build:

```bash
SKBUILD_CONFIGURE_OPTIONS="-DCOINCELLHELL_INCLUDE_DIRS=/usr/include -DCOINCELLHELL_LIBRARIES=/usr/lib/libcoincellhell_static.a" pip install .
```

---

## Quick start

```python
import coincellhell

# Connect to the first device, Coincellhell(12) connects to the device with serial 12
with coincellhell.Coincellhell() as device:
    heater = device.getHeater(0)
    heater.setMaxCurrent(200)
    heater.setTemperature(35.0)
    heater.setEnabled(True)

    while not device.checkReady():
        print(f"Heater 0 is at {heater.getTemperature()} degrees")

    cell = device.getCell(0)
    cell.setVoltageLimits(4.2, 2.5)
    cell.setChargeCurrent(0.01)
    cell.setState(coincellhell.CellState.CHARGING)
```

For a more complete example see the `example.py` script.

---

## API reference

The public symbols are re‑exported from the compiled ``_core`` module:

| Symbol | Description |
| --- | --- |
| `Coincellhell` | Device handle, counts heaters and cells, ready flag, led and triggers |
| `Heater` | One heater, temperature, setpoint, maximum current, enable, status |
| `Cell` | One coin cell channel, voltage limits, charge current, state, status |
| `HeaterStatus`, `CellStatus`, `TriggerStatus` | Read only snapshots of the device state |
| `Fault`, `TemperatureSensorLocation`, `TriggerState`, `TriggerType`, `CellState` | Enumerations |
| `CoincellhellError` | Raised by every command that fails, a subclass of `RuntimeError` |
| `list_available_devices()` | Serial numbers of the devices connected to this machine |
| `stringForFault(fault)` | Human readable description of a `Fault` |

Errors are signalled with exceptions, no return codes are handed out. When a
heater command fails and the heater reports a fault, the description from
`coincellhell_string_for_fault` is part of the exception message and is also
available as `HeaterStatus.faultString`.

The number of heaters and cells is currently fixed at four and exposed as
`HEATER_COUNT` and `CELL_COUNT`. `getHeaterCount()` and `getCellCount()` return
those constants today and will return the values reported by the device as soon
as the C API provides them, so code should always use the methods.

---

## License

`libcoincellhellpy` and `libcoincellhell` are licensed LGPL‑2.0‑or‑later.
