Skip to content

Diagnostic Plotting Tools

The regulator records several diagnostic logs internally and lets you download them as CSV files from the dashboard. The repository ships a set of Python plotting programs that read those CSV files and render detailed, interactive diagnostic plots — far more detail than the live plots in the browser. They are the tools used to tune the charging, voltage, and thermal control loops and to inspect alternator health data.

These run on your computer (not on the regulator). The workflow is always the same: capture a log on the device, download the CSV to your computer, then run the matching Python program, which automatically opens the newest matching file.

The programs live in the Python Post Processing Scripts/ folder of the public repository.

What Each Tool Does

Program Reads Shows
plot_thermallog.py thermallog_*.csv Temperature-loop behavior: alternator temperature, setpoint, thermal penalty, rate of rise, and the related state flags. ~2 hours of history at 1-second resolution.
plot_pidlog.py pidlog_*.csv Output current control loop (the inner PID): battery voltage versus target, the voltage-loop command chain, the current PID internals, and the duty-cycle pipeline versus measured amps. The last ~11 seconds at the full control-loop rate (~200 Hz).
plot_cvlog.py cvlog_*.csv Fixed-voltage (constant-voltage, "CV") tuning: voltage tracking, the current-command chain, the overvoltage protection layers, and engine RPM with control-loop timing jitter. The last ~28 seconds at ~200 Hz.
plot_altfront.py Alternator Health Data *.csv The alternator best-ever output front: every measured point of output current versus RPM, temperature, and excitation, as a coverage scatter and a selectable output curve.

One-Time Setup

You only do this once per computer.

1. Install Python

Install Python 3.9 or newer from python.org (macOS and Windows include the tkinter GUI library the file picker needs). On Linux, also install the system package python3-tk.

2. Get the programs

Clone the public repository (or download it as a ZIP and unpack it):

git clone https://github.com/markliquid1/Regulator2026-public.git

The programs are in the Python Post Processing Scripts/ subfolder.

3. Create a virtual environment and install the libraries

A virtual environment (an isolated Python install, "venv") keeps these libraries separate from the rest of your system. From a terminal:

python3 -m venv ~/plot-tools-venv
~/plot-tools-venv/bin/python -m pip install matplotlib pandas numpy

On Windows the paths use backslashes and Scripts instead of bin:

python -m venv %USERPROFILE%\plot-tools-venv
%USERPROFILE%\plot-tools-venv\Scripts\python -m pip install matplotlib pandas numpy

That is the entire setup. The same virtual environment runs all of the programs.

Capturing and Downloading a Log

This is what you do in the dashboard each time you want a fresh log to plot.

Control-loop, voltage, and temperature logs (Plots tab)

Open the Plots tab and stay on the Short Term sub-tab. The logging controls are at the top:

  • Pause Logs / Resume Logs — freezes or resumes the internal log buffers. The dot on the button shows the state (pulsing green = recording, amber = paused). Pause as soon as the event you care about has happened, so the buffer does not roll over and overwrite it before you download.
  • Download Logs — saves three CSV files to your Downloads folder (Files on a mobile device) and then clears the buffers:
    • thermallog_<timestamp>.csv — for plot_thermallog.py
    • pidlog_<timestamp>.csv — for plot_pidlog.py
    • cvlog_<timestamp>.csv — for plot_cvlog.py
  • Start Fresh Log — clears the buffers and begins a new log immediately.

A typical capture: press Start Fresh Log, let the regulator run through the behavior you want to study, press Pause Logs, then Download Logs.

Alternator health data (Alternator Health panel)

The alternator best-ever front is not part of the Plots tab. In the Alternator Health panel, press Download CSV. It saves a file named Alternator Health Data <timestamp>.csv to your Downloads folder, which is what plot_altfront.py reads.

Running a Tool

Each program automatically searches your Downloads folder and opens the newest matching CSV — you do not pass a filename. Run it from a terminal with the virtual environment's Python and the path to the program:

~/plot-tools-venv/bin/python "Python Post Processing Scripts/plot_pidlog.py"

Substitute whichever program you want. plot_thermallog.py, plot_pidlog.py, and plot_cvlog.py open a small list of recent CSV files in your Downloads folder so you can pick which capture to view; the others open the newest matching file directly. The plots are interactive — zoom and pan with the toolbar, and toggle individual traces on and off with the checkboxes beside each plot. Saved PNG copies land in your Downloads folder alongside the source CSV.

plot_altfront.py (alternator health)

This viewer has two tabs:

  • Overview — summary statistics and a coverage scatter (RPM versus temperature, color by output amps, dot size by sample count), plus an excitation-versus-amps scatter.
  • Output Curve — output amps versus a selectable X axis (RPM, excitation, or bus voltage), with points grouped into temperature bands. Sliders filter the RPM range, temperature range, and minimum sample count (confidence).

Every point on these plots is a real measured value; nothing is interpolated.

Trimming a Log to a Time Window

plot_thermallog.py, plot_pidlog.py, and plot_cvlog.py each include a built-in File Trimmer at the bottom of the window. Enter a start and end time in seconds (the window shows the file's full length, starting at 0) and it writes a trimmed copy to your Downloads folder named <original>_<start>s_<end>s.csv. The trimmed file opens in the same tool.

Trimming is mainly for AI-assisted analysis: feeding an LLM just the few seconds around the event, instead of the whole capture, cuts token cost and keeps it focused.