KINGSTON-115/llm-pid-tuner

설명

LLM‑PID‑Tuner는 물리적 시스템(히팅 플레이트, 모터, 오븐 등)의 PID 컨트롤러 튜닝을 도와주는 데스크톱 유틸리티로, 대규모 언어 모델(LLM)이 새로운 P, I, D 값을 제안하도록 합니다. 세 가지 모드로 작동합니다:

하드웨어 모드 – Arduino/ESP32(또는 다른 MCU)에서 시리얼 포트를 통해 실시간 CSV 데이터를 읽고, 데이터를 LLM에 보내고, 새로운 PID 설정값을 받아 보드에 다시 씁니다.
로컬 시뮬레이터 – Python 열 시스템 모델(simulator.py)을 실행하여 하드웨어 없이 튜닝 루프를 확인할 수 있습니다.
MATLAB/Simulink 모드 – MATLAB 엔진을 통해 Simulink PID 블록을 구동하고 LLM이 튜닝하도록 합니다. 이 프로그램은 초보자를 위해 기성 Windows .exe로 제공되지만, 소스는 Python으로 직접 실행할 수도 있습니다.

대상 사용자

이미 PID 제어 장치를 보유하고 있지만 적절한 게인을 찾는 데 어려움을 겪는 취미 개발자나 엔지니어.
하드웨어에 투자하기 전에 LLM 기반 제어 루프 최적화를 실험해보고 싶은 사람.
간단한 시리얼 CSV 프로토콜이나 Simulink 모델에 익숙한 사용자.

할 수 있는 일 (그리고 할 수 없는 일)

기능	세부 사항
실시간 PID 제안	센서/액추에이터 데이터를 읽고, 성능(오차, 오버슈트, 정상 상태)을 평가하고, LLM에 새 PID 설정값을 요청하고, 안전 제한을 적용하며, 성능이 저하되면 롤백할 수 있습니다.
시각화	데스크톱 UI(또는 TUI)는 실시간 곡선과 현재 PID 값을 표시하고, 설정값을 즉시 변경할 수 있습니다(`t` 키).
하드웨어 통합	시리얼을 통해 `timestamp_ms,setpoint,input,pwm,error,p,i,d`를 스트리밍하는 작은 Arduino/ESP32 펌웨어(`firmware.cpp`)를 사용합니다.
시뮬레이션	`simulator.py`는 열 시스템을 모방하여 보드 없이 전체 루프를 테스트할 수 있습니다.
Simulink 지원	MATLAB 엔진을 호출하여 Simulink 모델을 실행하고, 출력 신호를 읽고, PID 블록을 튜닝합니다.
오프라인 사용	`LLM_API_BASE_URL`을 로컬 서버로 지정하여 모든 OpenAI 호환 로컬 모델(Ollama, LM Studio 등)에서 작동합니다.
마법 버튼 컨트롤러가 아님	완벽한 제어를 보장하거나, 안전 회로를 대체하거나, 단독으로 벤치마크 수준의 성능을 생성하지는 않습니다.

시작하기 (빠른 시작)

최신 릴리스에서 Windows 실행 파일을 다운로드합니다(llm‑pid‑tuner.exe).
제공된 firmware.cpp를 실행하는 보드를 연결합니다(또는 동일한 CSV 시리얼 형식을 따르는 모든 장치). config.json에서 SERIAL_PORT를 AUTO 또는 실제 COM 포트로 설정합니다.
config.json을 편집합니다 – 최소한 LLM 필드를 채웁니다:
```
{
  "LLM_API_KEY": "sk‑your‑key",
  "LLM_API_BASE_URL": "https://api.openai.com/v1",
  "LLM_MODEL_NAME": "gpt-4o",
  "LLM_PROVIDER": "openai"
}
```
(URL을 변경하고 openai 프로바이더를 유지하면 로컬 모델도 사용할 수 있습니다.)
exe를 실행합니다 – 하드웨어 모드를 선택하고, 시리얼 포트를 스캔하게 하고, UI가 응답을 플롯하는지 확인합니다.
관찰합니다 – 도구가 자동으로 새 PID 값을 요청하고, 제한을 적용하며, 새 매개변수가 시스템을 악화시키면 롤백합니다. 오차, 오버슈트, 정상 상태 기준이 몇 회 연속으로 충족되면 튜닝이 중지됩니다.

하드웨어가 없다면 대신 시뮬레이터를 실행하세요: pip install -r requirements.txt && python simulator.py.

아키텍처 개요

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

시뮬레이터: 펌웨어와 동일한 CSV 스트림을 출력하는 난방 시스템의 Python 모델.
튜너: 코어 루프 – 데이터 읽기 → 평가 → LLM 호출 → 안전 적용 → 새 PID 쓰기.
펌웨어: CSV 프로토콜을 구현하고 PID 컨트롤러를 실행하는 최소한의 Arduino/ESP32 스케치.
데스크톱 런처(launcher.py)는 하드웨어와 시뮬레이션을 선택하고 GUI와 TUI를 전환할 수 있습니다.
지원 스크립트: doctor.py(환경 확인), system_id.py(스텝 응답 식별), pid_safety.py(제한 적용), benchmark.py(개발 테스트).

도구 구성

config.json – 기본 구성 파일. 첫 실행 시 자동 생성됩니다.
주요 섹션:
- 시리얼: SERIAL_PORT, BAUD_RATE, HARDWARE_PROFILE(기본값 generic_serial_csv).
- LLM: API 키, 기본 URL, 모델 이름, 프로바이더(openai, anthropic, openai_claude, orcarouter 등).
- 튜닝 동작: GOOD_ENOUGH_AVG_ERROR, GOOD_ENOUGH_OVERSHOOT, REQUIRED_STABLE_ROUNDS와 같은 임계값.
- Simulink: .slx 파일, PID 블록, 출력 신호, 선택적 MATLAB 루트 경로.
- 선택 사항: 프록시 설정, CSV 내보내기 경로, 사용자 정의 프롬프트 재정의.
환경 변수는 JSON 값을 재정의하며, CI나 비밀 관리에 유용합니다.

확장/사용자 정의

프롬프트 조정 – 세션 시작 시(사전 튜닝 대화 상자) 자연어 선호도를 입력하거나 llm/prompts.py를 편집하여 LLM이 받는 시스템 프롬프트를 변경합니다.
새 하드웨어 프로필 추가 – 예상 CSV 열 또는 사용자 정의 파서를 구현하고 프로필 이름을 config.json에 나열합니다.
LLM 교체 – OpenAI /v1/chat/completions 스키마를 따르는 모든 서비스가 작동합니다. LLM_API_BASE_URL과 LLM_PROVIDER만 변경하면 됩니다.
기여 – 리포지토리는 최신 기능용 dev 브랜치와 릴리스용 안정 main 브랜치를 사용합니다.

안전 주의 사항

튜너는 PID 게인만 제안하며 하드웨어 안전 회로를 대체하지 않습니다. 난방 장비 작업 시 항상 온도 제한, 워치독 타이머, 물리적 킬 스위치를 유지하십시오.

라이선스

MIT – 코드를 자유롭게 사용, 수정, 재배포할 수 있습니다.