xref: /openbmc/phosphor-pid-control/tuning.md (revision 23e22b90) 
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