Metadata-Version: 2.4
Name: power-monitor-zcu102
Version: 0.1.2
Summary: A Power Monitor tool for ZCU102 that reads INA226 power rails via hwmon.
Author-email: Darkhan Nurzhakyp <darkhan.nur12@gmail.com>
Project-URL: Homepage, https://github.com/drkh-n/power_monitor_zcu102
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Power Monitor ZCU102

The `power_monitor` tool provides a Python interface to accurately read INA226 power rails via the `hwmon` subsystems on the Xilinx Zynq UltraScale+ ZCU102 development board.

The design for this tool leverages the approach in the Xilinx EDA365 article: [Accurate Design Power Measurement Made Easier](https://xilinx.eda365.com/xilinx-article-detail.html?detail=22) by Don Matson and Luis Bielich.

---

## Power Calculation Formulas

The total power of the board is divided into three major domains: Processing System (PS), Programmable Logic (PL), and Multi-Gigabit Transceivers (MGT). The formulas used to calculate total power are derived from the reference article:

*   **PS Power** = VCCPSINTFP + VCCPSINTLP + VCCPSAUX + VCCPSPLL + VCCPSDDR + VCCOPS + VCCOPS3 + VCCPSDDRPL
*   **PL Power** = VCCINT + VCCBRAM + VCCAUX + VCC1V2 + VCC3V3
*   **MGT Power** = MGTRAVCC + MGTRAVTT + MGTAVCC + MGTAVTT
*   **Total Power** = PS Power + PL Power + MGT Power

*Note: While some legacy implementations vary where VCC3V3 is categorized, this tool adds it to PL as indicated by the formula structure in the article text.*

---

## INA226 Power Rails for ZCU102

The ZCU102 has shunt resistors placed on specific power rails, monitored by TI INA226 chips. These are accessible via the I2C bus exported to `/sys/class/hwmon` on PetaLinux systems. 

Here is the table of the relevant rails (referenced from the article and board parameters):

| Sensor Name | Rail / Domain Name | Category |
| :--- | :--- | :--- |
| `ina226_u76` | VCCPSINTFP | PS |
| `ina226_u77` | VCCPSINTLP | PS |
| `ina226_u78` | VCCPSAUX | PS |
| `ina226_u87` | VCCPSPLL | PS |
| `ina226_u93` | VCCPSDDR | PS |
| `ina226_u88` | VCCOPS | PS |
| `ina226_u15` | VCCOPS3 | PS |
| `ina226_u92` | VCCPSDDRPL | PS |
| `ina226_u79` | VCCINT | PL |
| `ina226_u81` | VCCBRAM | PL |
| `ina226_u80` | VCCAUX | PL |
| `ina226_u84` | VCC1V2 | PL |
| `ina226_u16` | VCC3V3 | PL |
| `ina226_u65` | VADJ_FMC | PL |
| `ina226_u85` | MGTRAVCC | MGT |
| `ina226_u86` | MGTRAVTT | MGT |
| `ina226_u74` | MGTAVCC | MGT |
| `ina226_u75` | MGTAVTT | MGT |

---

## Usage Example

Once the package is installed on the ZCU102 PetaLinux environment, you can use it in your Python scripts.

### 1. Simple Single Read
```python
from power_monitor import PowerMonitor

# Initialize the monitor
pm = PowerMonitor()

# Read the aggregated power domains once
ps, pl, mgt, total = pm._read_once(verbose=True)

print(f"Total Power: {total:.3f} W")
```

### 2. Background Measurement (Non-Blocking)
Useful for measuring power while a separate workload runs.
```python
import time
from power_monitor import PowerMonitor

pm = PowerMonitor(interval=0.5) # Sample every 0.5 seconds

print("Starting background power measurement...")
pm.start()

# Do your heavy workload here (e.g., neural network inference)
time.sleep(3.0) 

# Stop monitoring and retrieve records
pm.stop()

# Summarize and save
avg_ps, avg_pl, avg_mgt, avg_total = pm.average()
print(f"Average Total Power during workload: {avg_total:.3f} W")

pm.save_samples("power_log.csv")
```

---

## Installation 

### From source (PetaLinux 2022.2)

```bash
git clone <repository-url>
cd power_monitor
pip install .
```

---

## Running Automated Tests

The tests are specifically written to target the `hwmon` structures of the ZCU102 running PetaLinux. 

**Requirements:**
- A physical ZCU102 board running the PetaLinux 2022.2 image.
- `pytest` installed.

**To run the tests:**
1. Secure Shell (SSH) into the ZCU102 or use the serial terminal.
2. Navigate to the `power_monitor` project root.
3. Install pytest if needed: `pip install pytest`
4. Run the suite:
   ```bash
   python -m pytest tests/
   ```
