PID Tuner CLI

简体中文

PID Tuner CLI is a workspace-first command-line tool for PID tuning, experiment tracking, serial device interaction, and repeatable tuning sessions.

It is built for engineers who want a practical way to move from raw traces to parameter proposals without losing context, safety, or reproducibility.

Why Choose This Project?

• Workspace-first design: profiles, traces, proposals, sessions, and reports are stored in a structured local workspace.
• Safe by default: key write actions support --dry-run before touching profiles or devices.
• Automation-friendly: high-value commands support --json for scripts and tooling.
• Flexible tuning path: use the built-in heuristic backend first, then enable an LLM backend when needed.
• Hardware-aware: serial utilities are included for probing, monitoring, capturing, and sending PID values.

Quick Start

python -m pip install -e .
pid-tuner workspace init
pid-tuner trace simulate --profile speed --count 1
pid-tuner trace list
pid-tuner tune propose <trace-id>
pid-tuner tune apply <proposal-id> --dry-run

If you need LLM and serial integrations:

python -m pip install -e ".[llm,device]"

Supported Platforms

Platform	Status	Notes
Windows	Supported	Serial examples often use COM3-style port names.
macOS	Supported	Typical serial ports look like /dev/cu.usbserial-*.
Linux	Supported	Typical serial ports look like /dev/ttyUSB0 or /dev/ttyACM0.

Core functionality only requires Python 3.10+.

Serial features require pyserial.

LLM-backed proposal generation requires the openai package and a compatible API key.

When to Use

Use PID Tuner CLI when you want to:

• organize PID experiments as repeatable workspace data instead of ad-hoc files
• compare multiple traces before changing controller parameters
• generate tuning proposals from simulation, imported CSV traces, or captured device data
• iterate safely with previewable writes and machine-readable output
• integrate PID tuning into scripts, test benches, or lightweight lab workflows

It is especially useful when you need a single CLI that covers both offline analysis and device-facing tasks.

PID Tuner CLI Key Features

• Workspace management with persistent state
• Seeded control profiles for common PID loops
• CSV trace import, simulation, listing, preview, and analysis
• Heuristic proposal generation out of the box
• Optional LLM proposal backend
• Iterative tuning sessions with multiple cycles
• Serial device commands for probe, monitor, capture, and send-pid
• JSON output for automation
• --dry-run support for sensitive actions
• C code export for embedded integration

What Can You Do with PID Tuner CLI?

• initialize a clean tuning workspace
• define or inspect PID profiles
• simulate a response trace before touching hardware
• import measured CSV data and analyze control quality
• generate proposals and preview serial commands
• run multi-cycle tuning sessions
• capture live traces from a serial device
• export tuned values as C macros or structs

How PID Tuner CLI Works

1. Create or open a workspace.
2. Choose a profile that defines initial PID values, limits, and target metrics.
3. Produce a trace by importing CSV, simulating a loop, or capturing from a device.
4. Analyze the trace and calculate control metrics.
5. Generate a proposal using the heuristic backend or an optional LLM backend.
6. Review or apply the proposal, optionally pushing values to hardware.
7. Store the full flow as trace, proposal, session, and report data for later inspection.

Project Structure

project-root/
├── docs/                    # Architecture notes, examples, roadmap
├── examples/                # Placeholder for future sample assets
├── src/
│   └── pid_tuner_cli/
│       ├── adapters/        # External integrations such as serial and LLM backends
│       ├── core/            # Domain models, analysis, protocol, simulation, workspace
│       ├── services/        # Workflow orchestration for trace, tuning, session, report
│       ├── cli.py           # Main CLI parser and command dispatch
│       └── output.py        # Human-readable and JSON output rendering
├── tests/                   # Subprocess and domain-level tests
├── pyproject.toml
├── README.md
└── README.zh-CN.md

Command Groups

Command Group	Purpose
workspace	Initialize, inspect, and diagnose a workspace
profile	List, show, and create PID profiles
trace	Import, simulate, list, and inspect traces
analyze	Analyze stored traces or raw CSV files
tune	Generate, inspect, and apply tuning proposals
session	Run repeatable multi-step tuning workflows
device	Probe serial ports, monitor traffic, capture traces, send PID values
report	Summarize traces or sessions and export C code

Demo

Simulation-first flow:

pid-tuner workspace init
pid-tuner trace simulate --profile speed --count 1
pid-tuner trace list
pid-tuner analyze trace <trace-id>
pid-tuner tune propose <trace-id>
pid-tuner tune apply <proposal-id> --dry-run

Automation-friendly JSON flow:

pid-tuner --json workspace status
pid-tuner --json analyze trace <trace-id>
pid-tuner --json tune propose <trace-id>

Installation & Usage

Basic Installation

python -m pip install -e .

Optional Extras

python -m pip install -e ".[llm]"
python -m pip install -e ".[device]"
python -m pip install -e ".[llm,device]"

Run Directly from Source

PowerShell:

$env:PYTHONPATH = "src"
python -m pid_tuner_cli --help

Bash:

export PYTHONPATH=src
python -m pid_tuner_cli --help

Common Commands

Initialize a workspace:

pid-tuner workspace init
pid-tuner workspace status

Simulate and analyze:

pid-tuner trace simulate --profile speed --count 1
pid-tuner analyze trace <trace-id>

Generate a proposal:

pid-tuner tune propose <trace-id>
pid-tuner tune show <proposal-id>

Run a session:

pid-tuner session start --profile speed --source simulate
pid-tuner session iterate <session-id> --cycles 3 --apply

Use a device:

pid-tuner device probe --port COM3
pid-tuner device monitor --port COM3 --seconds 5
pid-tuner device capture --port COM3 --profile speed --duration 10
pid-tuner device send-pid --profile speed --dry-run

Use the LLM backend:

PowerShell:

$env:DEEPSEEK_API_KEY = "your_key"
pid-tuner tune propose <trace-id> --backend llm

Bash:

export DEEPSEEK_API_KEY="your_key"
pid-tuner tune propose <trace-id> --backend llm

Additional Notes

• The default local workspace is ./.pid-tuner-workspace.
• Runtime workspaces and temporary test output are ignored by Git.
• --dry-run is available on selected write operations for safer review.
• --json is recommended for scripts and external tooling.

Documentation

• Usage Examples
• CLI Architecture
• Product Analysis
• Project Scope
• Roadmap

Development

Run tests:

python -m unittest discover -s tests -v

Feedback and Contributions

Bug reports, edge cases, documentation issues, and workflow suggestions are all welcome.

If something feels unclear, inconsistent, or unsafe, please open an issue and point it out directly.

Pull requests are also welcome when they improve correctness, usability, or maintainability.

License

This project is released under the MIT License.