A workspace-based CLI for PID simulation, CSV analysis, reproducible tuning experiments, and STM32 serial integration.
Chinese is the primary user documentation: 简体中文说明.
Python 3.10 or newer is required.
python -m pip install -e .
pid-tuner init
pid-tuner quickstartquickstart initializes a workspace when necessary, simulates a response, validates and
analyzes the trace, and creates a heuristic proposal. It does not access a serial device or
apply parameters to an MCU.
If the short command is not available, use:
python -m pid_tuner_project_cli quickstart| Goal | Command |
|---|---|
| Diagnose the local setup | pid-tuner doctor |
| Analyze a CSV file | pid-tuner analyze file data.csv |
| List serial ports | pid-tuner ports |
| Save the default port | pid-tuner config serial --port COM3 |
| Verify STM32 telemetry | pid-tuner device verify --profile speed |
| Monitor MCU messages | pid-tuner device monitor --seconds 5 |
| Capture 100 samples | pid-tuner device capture --profile speed --count 100 |
| Preview a PID update | pid-tuner device send-pid --profile speed --dry-run |
| Run simulated BO | pid-tuner optimize run --profile speed --iterations 8 --live-view none |
Install optional integrations when needed:
python -m pip install -e ".[device]"
python -m pip install -e ".[llm]"The CLI consumes protocol v2 telemetry and requires correlated acknowledgements for updates:
DATA:<loop>:<time>,<target>,<actual>,<error>,<output>
PID:<request_id>:<loop>:<kp>,<ki>,<kd>
ACK:<request_id>:<loop>:<applied_kp>,<applied_ki>,<applied_kd>
NACK:<request_id>:<loop>:<reason>
An update succeeds only when request ID, loop name, and applied values all match. A timeout must not be treated as success.
The default workspace is ./.pid_tuner_project_cli-workspace and stores profiles, traces,
proposals, sessions, optimization runs, reports, and generated artifacts. Use a different path
by placing the global option before the command:
pid-tuner --workspace D:\pid-workspace init- Data-quality failures block proposal generation and application.
- Device writes should first be previewed with
--dry-run. - Device sessions require an explicit
--push-devicebefore applying to hardware. - Real-hardware BO is currently disabled;
optimize runsupports simulation only. - Firmware must independently implement output limits, watchdogs, emergency stops, sensor fault handling, and rollback.
- Chinese quick start
- STM32 and serial guide
- Command reference
- Architecture and safety boundaries
- STM32 firmware examples
$env:PYTHONPATH = "src"
python -m unittest discover -s tests -vThe project's own code is licensed under the MIT License.