# HIOKI 3193-10 Power Analyzer Tools

GPIB control tools for the HIOKI 3193-10 power analyzer, built for solar MPPT converter efficiency testing.

## Hardware Setup

- **HIOKI 3193-10** power analyzer with 9600 input units
- **GPIB-USB adapter**: [UsbGpib](https://github.com/xyphro/UsbGpib) — open-source USB-GPIB adapter, compatible with pyvisa (appears as a USB-TMC device)
- **NI-VISA runtime** — provides the VISA layer (`visa32.dll`)

The UsbGpib adapter connects to the HIOKI's rear GPIB port and is recognized by NI-VISA as a standard USB-TMC instrument, so it works seamlessly with pyvisa.

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- NI-VISA runtime (already installed if `visa32.dll` exists)
- UsbGpib adapter connected between PC and HIOKI 3193-10

## Install

```bash
uv sync
```

## Quick Start

```bash
# 1. Verify connection
uv run hioki identify

# 2. Configure for MPPT testing (Ch5=solar input, Ch6=MPPT output)
uv run hioki setup-mppt

# 3. Take a single reading
uv run hioki measure

# 4. Monitor continuously (prints to terminal)
uv run hioki monitor

# 5. Monitor with live graph
uv run hioki live
```

## Commands

### `hioki identify`

Show instrument identity, installed options, clock, wiring mode, and response speed.

### `hioki setup-mppt`

One-command setup for MPPT efficiency testing:
- Ch5: V-auto, I-auto, DC coupling, SLOW (solar panel input)
- Ch6: V-auto, I-auto, DC coupling, SLOW (MPPT converter output)
- EFF1 = P6/P5 x 100%
- Display: Ch5 items on left, Ch6 items on right, with EFF1

Both voltage and current auto-range for best accuracy across the full sweep range.

### `hioki measure [items...]`

Take a single measurement. Default items: `U5 I5 P5 U6 I6 P6 EFF1`

```bash
# Default (MPPT channels)
uv run hioki measure

# Custom items
uv run hioki measure U1 I1 P1 FA

# All 6 channels
uv run hioki measure U1 I1 P1 U2 I2 P2 U3 I3 P3 U4 I4 P4 U5 I5 P5 U6 I6 P6
```

### `hioki monitor [items...]`

Continuous text-based monitoring with optional CSV logging. When logging to CSV, voltage and current ranges are recorded per sample.

```bash
# Default 1-second interval
uv run hioki monitor

# Fast polling, 100 readings, save to CSV
uv run hioki monitor -i 0.5 -n 100 -o data.csv

# Monitor specific items
uv run hioki monitor P5 P6 EFF1
```

Options:
- `-i, --interval` - Seconds between readings (default: 1.0)
- `-n, --count` - Number of readings, 0 = infinite (default: 0)
- `-o, --output` - CSV output file path (includes U/I range columns)

### `hioki live [items...]`

Real-time graphing monitor. Opens a matplotlib window with live-updating plots grouped by type (voltage, current, power, efficiency).

```bash
# Default view
uv run hioki live

# Power and efficiency only, log to file
uv run hioki live -o test_log.csv P5 P6 EFF1

# Fast updates, shorter history
uv run hioki live -i 0.5 --history 100 U5 U6 P5 P6 EFF1
```

Options:
- `-i, --interval` - Seconds between readings (default: 1.0)
- `-o, --output` - CSV output file path (includes U/I range columns)
- `--history` - Max data points on graph (default: 300)

### `hioki display-select [items...]`

Configure the instrument's front panel display.

```bash
# MPPT preset: Ch5 left, Ch6 right, EFF1
uv run hioki display-select --mppt

# Custom 16-item layout
uv run hioki display-select U5 I5 P5 U6 I6 P6 EFF1
```

Options:
- `-c, --count` - Number of display slots: 4, 8, or 16 (default: 16)
- `--mppt` - Preset: Ch5 on left, Ch6 on right, with EFF1

### `hioki efficiency`

Configure efficiency calculation formula.

```bash
# EFF1 = P6/P5 (default from setup-mppt)
uv run hioki efficiency --numerator P6 --denominator P5

# EFF2 for a different pair
uv run hioki efficiency -f 2 -n P4 -d P3
```

### `hioki integration <action>`

Control energy integration (Wh, Ah totals).

```bash
uv run hioki integration start    # Reset and start integrating
uv run hioki integration status   # Check which channels are running
uv run hioki integration stop     # Stop and print Wh/Ah/time results
uv run hioki integration reset    # Reset counters
```

### `hioki send <command>`

Send raw SCPI/GPIB commands. Queries (containing `?`) return the response.

```bash
uv run hioki send *IDN?
uv run hioki send :VOLTage5:RANGe?
uv run hioki send :VOLTage5:RANGe 300
uv run hioki send *RST
```

## Global Options

- `-a, --address` - VISA address (auto-detects HIOKI if omitted)
- `--timeout` - Communication timeout in ms (default: 5000)

## CSV Output Format

When using `-o` with `monitor` or `live`, the CSV includes:
- `timestamp` - Date and time of each reading
- Measurement values (e.g., `U5`, `I5`, `P5`, `EFF1`)
- `U<ch>_range` - Active voltage range per channel (e.g., 150, 300)
- `I<ch>_range` - Active current range per channel (e.g., 0.2, 5, 50)

Range columns help identify auto-range transitions and assess measurement accuracy.

## Python API

Use the driver directly in your own scripts:

```python
from hioki3193 import Hioki3193

with Hioki3193("GPIB0::1::INSTR") as meter:
    print(meter.idn())

    # Configure
    meter.set_wiring_mode("1P2W")
    meter.set_coupling(5, "DC")
    meter.set_voltage_auto(5, True)
    meter.set_current_auto(5, True)
    meter.set_coupling(6, "DC")
    meter.set_voltage_auto(6, True)
    meter.set_current_auto(6, True)
    meter.set_response_speed("SLOW")
    meter.set_efficiency(1, "P6", "P5")

    # Read
    result = meter.measure("U5", "I5", "P5", "U6", "I6", "P6", "EFF1")
    print(f"Input:  {result.values['P5']:.2f} W")
    print(f"Output: {result.values['P6']:.2f} W")
    print(f"Efficiency: {result.values['EFF1']:.1f}%")
```

## Measurement Items

| Code | Description | Code | Description |
|------|-------------|------|-------------|
| U1-U6 | Voltage per channel | I1-I6 | Current per channel |
| P1-P6 | Active power | S1-S6 | Apparent power |
| Q1-Q6 | Reactive power | PF1-PF6 | Power factor |
| DEG1-DEG6 | Phase angle | PK1-PK6 | Peak value |
| FA,FB,FC | Frequency | EFF1-EFF3 | Efficiency |
| U12,P12... | Sum pairs | U123,P123... | Sum triples |
| WP1-WP6 | Integrated Wh | IH1-IH6 | Integrated Ah |
| TIME | Integration elapsed time | | |

## Error Values

When reading data, these special values indicate errors:
- `+6666.6E+99` - Display blank (no data)
- `+7777.7E+99` - Scaling error (e.g., division by zero in efficiency)
- `+9999.9E+99` - Input over range

## Reference

See `GPIB_COMMAND_REFERENCE.txt` for the complete command reference extracted from the HIOKI 3193-10 manual.