KINGSTON-115/llm-pid-tuner

What it is

LLM‑PID‑Tuner is a desktop‑style utility that helps you tune the PID controller of a physical system (heating plate, motor, oven, etc.) by letting a large language model (LLM) suggest new P, I, D values. It can work in three modes:

Hardware mode – reads live CSV data from an Arduino/ESP32 (or other MCU) over a serial port, sends the data to an LLM, receives a new PID set‑point and writes it back to the board.
Local simulator – runs a Python heat‑system model (simulator.py) so you can see the tuning loop without any hardware.
MATLAB/Simulink mode – drives a Simulink PID block via the MATLAB Engine and lets the LLM tune it. The program ships as a ready‑made Windows .exe for beginners, but the source can also be run directly with Python.

Who it’s for

Hobbyists or engineers who already have a PID‑controlled device but struggle to find good gains.
Anyone who wants to experiment with LLM‑driven control‑loop optimisation before committing to hardware.
Users comfortable with a simple serial‑CSV protocol or with a Simulink model.

What it does (and doesn’t)

Capability	Details
Real‑time PID suggestion	Reads sensor/actuator data, evaluates performance (error, overshoot, steady‑state), asks the LLM for a new PID set‑point, applies safety limits, and can roll back if performance degrades.
Visualization	Desktop UI (or TUI) shows live curves, current PID values, and lets you change the set‑point on the fly (`t` key).
Hardware integration	Uses a tiny Arduino/ESP32 firmware (`firmware.cpp`) that streams `timestamp_ms,setpoint,input,pwm,error,p,i,d` over serial.
Simulation	`simulator.py` mimics a thermal system so you can test the whole loop without a board.
Simulink support	Calls MATLAB Engine to run a Simulink model, reads the output signal, and tunes the PID block.
Offline use	Works with any OpenAI‑compatible local model (Ollama, LM Studio, etc.) by pointing `LLM_API_BASE_URL` to the local server.
Not a magic‑button controller	It does not guarantee perfect control, replace safety circuits, or produce benchmark‑level performance on its own.

How to get started (quick‑start)

Download the Windows executable from the latest Release (llm‑pid‑tuner.exe).
Connect a board that runs the provided firmware.cpp (or any device that follows the same CSV serial format). Set SERIAL_PORT to AUTO or the actual COM port in config.json.

Edit config.json – at minimum fill the LLM fields:

{
  "LLM_API_KEY": "sk‑your‑key",
  "LLM_API_BASE_URL": "https://api.openai.com/v1",
  "LLM_MODEL_NAME": "gpt-4o",
  "LLM_PROVIDER": "openai"
}

(You can also use local models by changing the URL and keeping openai as the provider.)

Run the exe – choose hardware mode, let it scan the serial ports, and watch the UI plot the response.
Observe – the tool will automatically request new PID values, enforce limits, and roll back if the new parameters make the system worse. When the error, overshoot and steady‑state criteria are met for a few consecutive rounds, tuning stops.

If you have no hardware, run the simulator instead: pip install -r requirements.txt && python simulator.py.

Architecture at a glance

+-------------------+        +-------------------+        +-------------------+
| Local simulator   |  API   | LLM / AI tuner    |  API   | Real hardware     |
| (simulator.py)    |<------>| (tuner.py)        |<------>| (firmware.cpp)    |
+-------------------+        +-------------------+        +-------------------+

Simulator: a Python model of a heating system that outputs the same CSV stream as the firmware.
Tuner: core loop – read data → evaluate → call LLM → apply safety → write new PID.
Firmware: minimal Arduino/ESP32 sketch that implements the CSV protocol and runs the PID controller.
Desktop launcher (launcher.py) lets you pick hardware vs. simulation and switches between GUI and TUI.
Support scripts: doctor.py (environment check), system_id.py (step‑response identification), pid_safety.py (limit enforcement), benchmark.py (dev testing).

Configuring the tool

config.json – primary configuration file; automatically generated on first run.
Key sections:
- Serial: SERIAL_PORT, BAUD_RATE, HARDWARE_PROFILE (default generic_serial_csv).
- LLM: API key, base URL, model name, provider (openai, anthropic, openai_claude, orcarouter, etc.).
- Tuning behaviour: thresholds such as GOOD_ENOUGH_AVG_ERROR, GOOD_ENOUGH_OVERSHOOT, REQUIRED_STABLE_ROUNDS.
- Simulink: paths to the .slx file, PID block, output signal, optional MATLAB root.
- Optional: proxy settings, CSV export path, custom prompt overrides.
Environment variables override the JSON values, which is handy for CI or secret management.

Extending / customizing

Prompt tweaking – either type natural‑language preferences at the start of a session (pre‑tuning dialog) or edit llm/prompts.py to change the system prompt that the LLM receives.
Add a new hardware profile – implement the expected CSV columns or a custom parser and list the profile name in config.json.
Swap the LLM – any service that follows the OpenAI /v1/chat/completions schema works; just change LLM_API_BASE_URL and LLM_PROVIDER.
Contribute – the repo uses a dev branch for the latest features and a stable main branch for releases.

Safety note

The tuner only suggests PID gains; it does not replace hardware safety circuits. Always keep temperature limits, watchdog timers, and a physical kill‑switch when working with heating equipment.

License

MIT – you can freely use, modify, and redistribute the code.