1926411e1SKun Yi# PID Control Tuning & Logging 2926411e1SKun Yi 3926411e1SKun YiThe openBMC PID control daemon, swampd (phosphor-pid-control) requires the user 4926411e1SKun Yito specify the sensors and PID coefficients. Determining good coefficients is 5926411e1SKun Yibeyond the scope of this document. 6926411e1SKun Yi 7*217a827dSPatrick Williams**NOTE** The steps below may not be applicable if you are using D-Bus based 8*217a827dSPatrick Williamsconfiguration. 9926411e1SKun Yi 10926411e1SKun Yi## Tuning Fan PID Using a Fixed RPM Setpoint 11926411e1SKun Yi 12926411e1SKun YiFlag `"-t"` can be specified to enabled the daemon to read the fan RPM setpoint 13926411e1SKun Yifrom a file `/etc/thermal.d/setpoint` instead from D-Bus. 14926411e1SKun Yi 15926411e1SKun YiThe value in the setpoint file is expected to be a normal decimal integer, such 16926411e1SKun Yias `4000` or `5000`, and is in RPM. 17926411e1SKun Yi 18926411e1SKun Yi## Tuning Fan PID Control Parameters 19926411e1SKun Yi 20926411e1SKun Yi`phosphor-pid-control` reads PID control values from 21926411e1SKun Yi`/usr/share/swampd/config.json`, one can modify the PID parameters in the config 22926411e1SKun Yifile and restart the daemon to make the new values effective. 23926411e1SKun Yi 24926411e1SKun Yi``` 25a7ec8350SPatrick Venturesystemctl restart phosphor-pid-control.service 26926411e1SKun Yi``` 27926411e1SKun Yi 28926411e1SKun Yi## Logging 29926411e1SKun Yi 30926411e1SKun YiFlag `"-l \<path\>"` can be specified to enable the daemon to log fan control 31926411e1SKun Yidata into `path`. The log output is in CSV format with the following header: 32926411e1SKun Yi 33926411e1SKun Yi``` 34926411e1SKun Yiepoch_ms,setpt,fan1,fan2,...fanN,fleeting,failsafe 35926411e1SKun Yi``` 36926411e1SKun Yi 37926411e1SKun Yi`phosphor-pid-control` will create a log for each PID control zone. 38926411e1SKun Yi 39de74542cSJosh Lehan## Core Logging 40de74542cSJosh Lehan 41*217a827dSPatrick WilliamsFor even more detailed logging, flag `"-g"` can be specified to enable the 42*217a827dSPatrick Williamsdaemon to log the computations made during the core of the PID loop. 43de74542cSJosh Lehan 44*217a827dSPatrick WilliamsThe log output is in CSV format, in the same directory as specified with the 45*217a827dSPatrick Williams`"-l"` option. Default is the system temporary directory, typically `/tmp`. 46de74542cSJosh Lehan 47*217a827dSPatrick WilliamsTwo files will be created, for each PID loop configured. The `pidcoeffs.*` file 48*217a827dSPatrick Williamswill show the PID coefficients that are in use for the PID loop. The `pidcore.*` 49*217a827dSPatrick Williamsfile will show the computations that take place, to transform the input into the 50*217a827dSPatrick Williamsoutput. The configured name of the PID loop is used as the suffix, for both of 51*217a827dSPatrick Williamsthese files. 52de74542cSJosh Lehan 53*217a827dSPatrick WilliamsThe `pidcoeffs.*` file will grow slowly, updated only when new coefficients are 54*217a827dSPatrick Williamsset using D-Bus without restarting the program. The `pidcore.*` file, on the 55*217a827dSPatrick Williamsother hand, will grow rapidly, as it will be updated during each PID loop pass 56*217a827dSPatrick Williamsin which there were changes. To prevent needless log file growth, identical 57*217a827dSPatrick Williamslogging lines are throttled, unless it has been at least 60 seconds since the 58*217a827dSPatrick Williamslast line. 59de74542cSJosh Lehan 60926411e1SKun Yi## Fan RPM Tuning Helper script 61926411e1SKun Yi 62926411e1SKun Yi`https://github.com/openbmc/phosphor-pid-control/blob/master/tools/fan_rpm_loop_test.sh` 63926411e1SKun Yiis an example script on how to sweep through available RPM setpoints and log the 64926411e1SKun Yifan responses. 65926411e1SKun Yi 66926411e1SKun Yi## Thermal Tuning Example 67926411e1SKun Yi 68926411e1SKun Yi1. Create initial `/usr/share/swampd/config.json` used for PID control 69926411e1SKun Yi2. (Option 1) If using a fixed setpoint, write the value to 70*217a827dSPatrick Williams `/etc/thermal.d/setpoint`, run swampd manually with 71*217a827dSPatrick Williams `swampd -l ${LOG_PATH}&`, and kill the process after desired duration. 72*217a827dSPatrick Williams3. (Option 2) If sweeping fan setpoint, using the tuning helper script 73*217a827dSPatrick Williams `fan_rpm_loop_test.sh` to configure fan setpoint in steps and collect logs 74926411e1SKun Yi4. Parse logs from `${LOG_PATH}/zone_*.log` and analyze response data 75*217a827dSPatrick Williams5. Modify `/usr/share/swampd/config.json` as needed 76*217a827dSPatrick Williams6. Repeat from step 2 or step 3 77