pid_tuner_project_cli

English | 简体中文 | 繁體中文

pid_tuner_project_cli is a workspace-first command-line tool for PID tuning, experiment tracking, serial device interaction, repeatable tuning sessions, and Bayesian optimization runs with live visualization.

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.
• Optimization-first workflow: run bayes_only or bayes_llm search jobs and watch progress in a live matplotlib view.
• Hardware-aware: serial utilities are included for probing, monitoring, capturing, and sending PID values.

Quick Start

python -m pip install -e .
pid_tuner_project_cli workspace init
pid_tuner_project_cli trace simulate --profile speed --count 1
pid_tuner_project_cli trace list
pid_tuner_project_cli tune propose <trace-id>
pid_tuner_project_cli tune apply <proposal-id> --dry-run
pid_tuner_project_cli optimize run --profile speed --mode bayes_only --iterations 8

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 and bayes_llm optimization mode require the openai package and a compatible API key.

When to Use

Use pid_tuner_project_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
• run Bayesian optimization with live progress visualization and archived output artifacts
• 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_project_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
• Bayesian optimization runs with bayes_only and bayes_llm modes
• Realtime matplotlib monitoring during optimization runs
• Per-run output/<run-id> artifacts: JSON, HTML report, PNG snapshots, and per-trial traces
• 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_project_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 a live optimization job and review the resulting artifact bundle
• run multi-cycle tuning sessions
• capture live traces from a serial device
• export tuned values as C macros or structs

How pid_tuner_project_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. Run optimize for live Bayesian search when you want iterative exploration instead of a single proposal.
7. Review or apply the proposal, optionally pushing values to hardware.
8. Store the full flow as trace, proposal, session, optimization run, and report data for later inspection.

Project Structure

project-root/
├── docs/                    # Architecture notes, examples, roadmap
├── examples/                # Placeholder for future sample assets
├── src/
│   └── pid_tuner_project_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
optimize	Run Bayesian optimization with live monitoring and per-run artifacts
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_project_cli workspace init
pid_tuner_project_cli trace simulate --profile speed --count 1
pid_tuner_project_cli trace list
pid_tuner_project_cli analyze trace <trace-id>
pid_tuner_project_cli tune propose <trace-id>
pid_tuner_project_cli tune apply <proposal-id> --dry-run

Automation-friendly JSON flow:

pid_tuner_project_cli --json workspace status
pid_tuner_project_cli --json analyze trace <trace-id>
pid_tuner_project_cli --json tune propose <trace-id>

Optimization flow with live view:

pid_tuner_project_cli workspace init
pid_tuner_project_cli optimize run --profile speed --mode bayes_only --strategy standard_bo --iterations 12
pid_tuner_project_cli optimize run --profile speed --mode bayes_llm --strategy digit_hierarchical --iterations 12
pid_tuner_project_cli optimize list
pid_tuner_project_cli optimize show <run-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_project_cli --help

Bash:

export PYTHONPATH=src
python -m pid_tuner_project_cli --help

Common Commands

Initialize a workspace:

pid_tuner_project_cli workspace init
pid_tuner_project_cli workspace status

Simulate and analyze:

pid_tuner_project_cli trace simulate --profile speed --count 1
pid_tuner_project_cli analyze trace <trace-id>

Generate a proposal:

pid_tuner_project_cli tune propose <trace-id>
pid_tuner_project_cli tune show <proposal-id>

Run a session:

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

Run Bayesian optimization:

pid_tuner_project_cli optimize run --profile speed --mode bayes_only --iterations 12
pid_tuner_project_cli optimize run --profile speed --mode bayes_llm --strategy digit_hierarchical --iterations 12
pid_tuner_project_cli optimize list

Use a device:

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

Use the LLM backend:

PowerShell:

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

Bash:

export DEEPSEEK_API_KEY="your_key"
pid_tuner_project_cli tune propose <trace-id> --backend llm
pid_tuner_project_cli optimize run --profile speed --mode bayes_llm --iterations 12

Optimization Output

Each optimization run writes a dedicated artifact bundle to:

.pid_tuner_project_cli-workspace/output/<run-id>/

Typical contents:

• dashboard.json: structured data for charts, trial history, and GP slices
• report.html: standalone report page
• summary.json: best PID, best score, and run summary
• trials.json: full per-trial log
• live_snapshot.png: latest saved live figure snapshot
• trace_001.csv, trace_002.csv, ...: response traces for each trial

By default, optimize run opens a realtime matplotlib window. Use --live-view none when running headless.

Additional Notes

• The default local workspace is ./.pid_tuner_project_cli-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.
• optimize run v1 currently supports --source simulate; device optimization is intentionally reserved for a later guarded implementation.

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.