Metadata-Version: 2.4
Name: digipigi
Version: 1.0.0
Summary: API to use the digipigi
Home-page: https://gitlab.phys.ethz.ch/code/experiment/digipigi
Author: Sebastian Huber
Author-email: huberse@phys.ethz.ch
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.18.0
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# digipigi

Python client for the **digipigi**: a network-attached, digitally controlled attenuator for square-wave drive
signals. A Raspberry Pi with a small hat sets a digital potentiometer, so the amplitude of a 0-3.3 V
input signal can be scaled in 256 steps from a remote PC over TCP.

## Installation

```bash
pip install digipigi          # or: uv pip install digipigi
```

Python ≥ 3.8 and numpy are required.

## Quick start

```python
import digipigi

dp = digipigi.DigiPigi(HOST="digipigi1-cmtqo")   # PORT=60606 by default
att = dp.setAttenuation(128)                    # set wiper code 128 (0 ... 255)
print(att)                                      # calibrated out/in factor, here ≈ 0.496
```

`setAttenuation(code)` sends one wiper code (integer 0-255) to the server on the Pi and returns the
calibrated attenuation factor *output/input* for that code. It returns `None` (and prints the reason) if the
connection fails or the server rejects the value.

## Calibration tables (`load=`)

The returned factor comes from a calibration table chosen with `load` when the object is created:

| `load` | Hardware | Valid for |
|---|---|---|
| `"c_revC_10kOhm"` (default) | hat rev C | 10 kΩ load, e.g. the input of an Aim-TTi RF amplifier; = `c_revC` × 10 kΩ / (10 kΩ + 49.9 Ω) |
| `"c_revC"` | hat rev C | high-impedance load (measured with an Analog Discovery 2, 1 MΩ) |
| `"c10kOhm"` | hat rev A (old) | 10 kΩ load |
| `"c10MOhm"` | hat rev A (old) | high-impedance load |

```python
dp = digipigi.DigiPigi(HOST="digipigi1-cmtqo", load="c_revC")
```

For another resistive load R on a rev C hat, multiply the `c_revC` value by R / (R + 49.9 Ω).

## Hardware revisions

- **Rev C (current):** MCP41010 10 kΩ digital potentiometer on 3.3 V, followed by an OPA350 voltage follower
  and a 49.9 Ω output resistor. The DC attenuation is linear: out/in = 0.9977 × code/256 − 0.0007,
  deviation from that line ≤ 0.0006, monotonic. It is independent of the load down to ~1 kΩ apart from the
  49.9 Ω divider. At 500 kHz the edges at mid codes are slower than at full scale (time constant ≈ 0.1 µs,
  ≈ 20° phase lag at mid codes). This comes from the potentiometer's resistor ladder and depends on the code,
  but deterministically.
- **Rev A (old):** MCP4151, wiper directly on the output. The attenuation depends on the load (up to 20 %
  low at mid codes into 10 kΩ), and the edge speed depends on the code and the cable.

The server on the Pi must match the potentiometer: rev C needs the SPI write command `0x11`, rev A `0x00`.
This is set with the Ansible variable `digipot` in the project repository.

## Limits

- Input signal: 0 ... 3.3 V (unipolar, e.g. a 3.3 V logic square wave).
- Lowest codes (output of a few mV) are limited by the calibration resolution (~0.6 mV).
- Don't drive 50 Ω loads: the output halves and the op-amp current exceeds ±30 mA.

## Project, server and calibration

The Raspberry Pi setup (Ansible playbooks), the socket server, the KiCad files of the hats and the
calibration procedure (`calibrate.py`, wiring in `CALIBRATION.md`) are in the project repository:
<https://gitlab.phys.ethz.ch/code/experiment/digipigi>.

## Releasing (maintainers)

Releases are built and uploaded to PyPI by GitLab CI when a tag is pushed. The version number comes from the
tag (`v1.2.3` → `1.2.3`, via setuptools-scm):

```bash
git tag -a v1.0.0 -m "release notes" && git push origin v1.0.0
```

The CI variable `PYPI_TOKEN` must hold a PyPI API token.
