docs: Add a small guide for thermal tuning

Add a guide explaining the tuning procedure and logging
format, and point README to it

Signed-off-by: Kun Yi <kunyi731@gmail.com>
Change-Id: I287b0ef4a5ede1c62751d1671e2eec188133a074

2 files changed, 56 insertions, 0 deletions

diff --git a/README.md b/README.md
index 2b5e0b9..366e053 100644
--- a/README.md
+++ b/README.md
@@ -261,6 +261,8 @@ The log files will be named {folderpath}/zone_{zoneid}.log
 
 To enable tuning, pass "-t" on the command line.
 
+See [Logging & Tuning](tuning.md) for more information.
+
 ## Project Information
 
 This project is designed to be a daemon running within the OpenBMC environment.
diff --git a/tuning.md b/tuning.md
new file mode 100644
index 0000000..efb5e92
--- /dev/null
+++ b/tuning.md
@@ -0,0 +1,54 @@
+# PID Control Tuning & Logging
+
+The openBMC PID control daemon, swampd (phosphor-pid-control) requires the user
+to specify the sensors and PID coefficients. Determining good coefficients is
+beyond the scope of this document.
+
+**NOTE** The steps below may not be applicable if you are using D-Bus based configuration.
+
+## Tuning Fan PID Using a Fixed RPM Setpoint
+
+Flag `"-t"` can be specified to enabled the daemon to read the fan RPM setpoint
+from a file `/etc/thermal.d/setpoint` instead from D-Bus.
+
+The value in the setpoint file is expected to be a normal decimal integer, such
+as `4000` or `5000`, and is in RPM.
+
+## Tuning Fan PID Control Parameters
+
+`phosphor-pid-control` reads PID control values from
+`/usr/share/swampd/config.json`, one can modify the PID parameters in the config
+file and restart the daemon to make the new values effective.
+
+```
+systemctl restart swampd.service
+```
+
+## Logging
+
+Flag `"-l \<path\>"` can be specified to enable the daemon to log fan control
+data into `path`. The log output is in CSV format with the following header:
+
+```
+epoch_ms,setpt,fan1,fan2,...fanN,fleeting,failsafe
+```
+
+`phosphor-pid-control` will create a log for each PID control zone.
+
+## Fan RPM Tuning Helper script
+
+`https://github.com/openbmc/phosphor-pid-control/blob/master/tools/fan_rpm_loop_test.sh`
+is an example script on how to sweep through available RPM setpoints and log the
+fan responses.
+
+## Thermal Tuning Example
+
+1.  Create initial `/usr/share/swampd/config.json` used for PID control
+2.  (Option 1) If using a fixed setpoint, write the value to
+    `/etc/thermal.d/setpoint`, run swampd manually with `swampd -l ${LOG_PATH}&`, and kill the
+    process after desired duration.
+3.  (Option 2) If sweeping fan setpoint, using the tuning helper script `fan_rpm_loop_test.sh` to
+    configure fan setpoint in steps and collect logs
+4.  Parse logs from `${LOG_PATH}/zone_*.log` and analyze response data
+6.  Modify `/usr/share/swampd/config.json` as needed
+7.  Repeat from step 2 or step 3