amd-monitor/README.md

# AMD TUF Power Monitor

Two small utilities live here:

- `amd-monitor.sh` – a one‑second loop that reads AMD APU/dGPU telemetry from `/sys/class/hwmon`, prints a live dashboard, and appends the readings to `power_log.csv`.
- `plot_power.py` – turns the CSV log into a bar + line chart so you can visualize power draw and temperatures after a capture session.

The scripts were built for an ASUS TUF laptop running Debian 13, but they should work on any recent AMD system that exposes the same hwmon files.

## Requirements

- Bash (already on most Linux installs).
- Read access to the hwmon entries for your APU and GPU. On some systems you need to run the script with `sudo` or add yourself to the `video` group.
- Python 3.9+ with `pandas` and `matplotlib` (`pip install pandas matplotlib`) for plotting.

## Usage Flow

1. **Collect live telemetry**
   ```bash
   chmod +x amd-monitor.sh
   ./amd-monitor.sh
   ```
   - The script clears the terminal and prints APU/GPU wattage, temperatures, and total power every second.
   - Each sample is appended to `power_log.csv` as `timestamp,apu_w,gpu_w,total_w,apu_temp,gpu_temp`.
   - The file is capped at the most recent 500 lines; tweak `MAX_LINES` if you want longer captures.

2. **Adjust sensor paths if needed**
   - Edit the `APU_HWMON` and `GPU_HWMON` variables near the top of `amd-monitor.sh` so they point to the correct `/sys/class/hwmon/...` folders on your machine.
   - You can also change `INTERVAL` for faster/slower sampling and `LOGFILE` if you want a different CSV name.

3. **Plot the results**
   ```bash
   python3 plot_power.py
   ```
   - The script reads `power_log.csv` (assumed to be headerless), down-samples if there are more than ~200 records, and saves `power_graph.png`.
   - Power traces are displayed as grouped bars (APU, GPU, total) while temperatures are overlaid as dashed lines on a secondary axis.

## Tips

- Keep `amd-monitor.sh` running while you stress the system (games, benchmarks, etc.), then stop it with `Ctrl+C` before plotting.
- If you need to log multiple sessions, rename or move `power_log.csv` between runs so plots only cover the period you care about.
- Want live graphing or more metrics? Extend the CSV schema and the plotting script—the code is intentionally short and hackable.

## Forgejo workflow

A Forgejo workflow (`.forgejo/workflows/power-graph.yml`) automates the chart generation whenever `power_log.csv` changes on the `master` branch.

What it does:

1. Runs on a self-hosted runner for separation of processing (You will need to set one up if using forgejo).
2. Manually clones the repo with a read token stored in `secrets.PAT_READ_REPO`.
3. Installs Python (via `apt`), prepares a virtualenv, and pulls `pandas` + `matplotlib`.
4. Executes `python plot_power.py`, producing `power_graph.png`.
5. Uploads the PNG as a Forgejo artifact (`power-graph`), so you can download the rendered plot from the workflow page.

To use it, push an updated `power_log.csv` to `master`, wait for the workflow to finish, then grab the artifact from the run summary. Update the workflow if your runner already has Python or if you want different triggers/retention.