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