1# PID Control Tuning & Logging 2 3The openBMC PID control daemon, swampd (phosphor-pid-control) requires the user 4to specify the sensors and PID coefficients. Determining good coefficients is 5beyond the scope of this document. 6 7**NOTE** The steps below may not be applicable if you are using D-Bus based configuration. 8 9## Tuning Fan PID Using a Fixed RPM Setpoint 10 11Flag `"-t"` can be specified to enabled the daemon to read the fan RPM setpoint 12from a file `/etc/thermal.d/setpoint` instead from D-Bus. 13 14The value in the setpoint file is expected to be a normal decimal integer, such 15as `4000` or `5000`, and is in RPM. 16 17## Tuning Fan PID Control Parameters 18 19`phosphor-pid-control` reads PID control values from 20`/usr/share/swampd/config.json`, one can modify the PID parameters in the config 21file and restart the daemon to make the new values effective. 22 23``` 24systemctl restart phosphor-pid-control.service 25``` 26 27## Logging 28 29Flag `"-l \<path\>"` can be specified to enable the daemon to log fan control 30data into `path`. The log output is in CSV format with the following header: 31 32``` 33epoch_ms,setpt,fan1,fan2,...fanN,fleeting,failsafe 34``` 35 36`phosphor-pid-control` will create a log for each PID control zone. 37 38## Core Logging 39 40For even more detailed logging, flag `"-g"` can be specified 41to enable the daemon to log the computations made during the core 42of the PID loop. 43 44The log output is in CSV format, in the same directory as specified with 45the `"-l"` option. Default is the system temporary directory, 46typically `/tmp`. 47 48Two files will be created, for each PID loop configured. The 49`pidcoeffs.*` file will show the PID coefficients that are in use 50for the PID loop. The `pidcore.*` file will show the computations 51that take place, to transform the input into the output. The configured 52name of the PID loop is used as the suffix, for both of these files. 53 54The `pidcoeffs.*` file will grow slowly, updated only when new 55coefficients are set using D-Bus without restarting the program. The 56`pidcore.*` file, on the other hand, will grow rapidly, as it will 57be updated during each PID loop pass in which there were changes. To 58prevent needless log file growth, identical logging lines are 59throttled, unless it has been at least 60 seconds since the last line. 60 61## Fan RPM Tuning Helper script 62 63`https://github.com/openbmc/phosphor-pid-control/blob/master/tools/fan_rpm_loop_test.sh` 64is an example script on how to sweep through available RPM setpoints and log the 65fan responses. 66 67## Thermal Tuning Example 68 691. Create initial `/usr/share/swampd/config.json` used for PID control 702. (Option 1) If using a fixed setpoint, write the value to 71 `/etc/thermal.d/setpoint`, run swampd manually with `swampd -l ${LOG_PATH}&`, and kill the 72 process after desired duration. 733. (Option 2) If sweeping fan setpoint, using the tuning helper script `fan_rpm_loop_test.sh` to 74 configure fan setpoint in steps and collect logs 754. Parse logs from `${LOG_PATH}/zone_*.log` and analyze response data 766. Modify `/usr/share/swampd/config.json` as needed 777. Repeat from step 2 or step 3 78