xref: /openbmc/phosphor-pid-control/tuning.md (revision 98b704e1) 
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 swampd.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## Fan RPM Tuning Helper script
39
40`https://github.com/openbmc/phosphor-pid-control/blob/master/tools/fan_rpm_loop_test.sh`
41is an example script on how to sweep through available RPM setpoints and log the
42fan responses.
43
44## Thermal Tuning Example
45
461.  Create initial `/usr/share/swampd/config.json` used for PID control
472.  (Option 1) If using a fixed setpoint, write the value to
48    `/etc/thermal.d/setpoint`, run swampd manually with `swampd -l ${LOG_PATH}&`, and kill the
49    process after desired duration.
503.  (Option 2) If sweeping fan setpoint, using the tuning helper script `fan_rpm_loop_test.sh` to
51    configure fan setpoint in steps and collect logs
524.  Parse logs from `${LOG_PATH}/zone_*.log` and analyze response data
536.  Modify `/usr/share/swampd/config.json` as needed
547.  Repeat from step 2 or step 3
55