README: start adding configuration details
Add details for configuring the sensor. Not yet the zones.
Signed-off-by: Patrick Venture <venture@google.com>
Change-Id: I073a4dde4fd6c785ffaea2daed03ebbe83d0d1d2
diff --git a/README.md b/README.md
index fb41094..e34fbef 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,10 @@
The system will run a control loop for each zone with the attempt to maintain
the temperature within that zone within the margin for the devices specified.
+## Configuring
+
+[How to configure phosphor-pid-control](configure.md)
+
## Detailed Design
The software will run as a multi-threaded daemon that runs a control loop for
diff --git a/configure.md b/configure.md
new file mode 100644
index 0000000..0a65791
--- /dev/null
+++ b/configure.md
@@ -0,0 +1,109 @@
+# How to Configure Phosphor-pid-control
+
+A system needs two groups of configurations: zones and sensors.
+
+## Json Configuration
+
+```
+{
+ "sensors" : [
+ {
+ "name": "fan1",
+ "type": "fan",
+ "readPath": "/xyz/openbmc_project/sensors/fan_tach/fan1",
+ "writePath": "/sys/devices/platform/ahb/ahb:apb/1e786000.pwm-tacho-controller/hwmon/**/pwm1",
+ "min": 0,
+ "max": 255
+ },
+ {
+ "name": "fan2",
+ "type": "fan",
+ "readPath": "/xyz/openbmc_project/sensors/fan_tach/fan2",
+ "writePath": "/sys/devices/platform/ahb/ahb:apb/1e786000.pwm-tacho-controller/hwmon/**/pwm2",
+ "min": 0,
+ "max": 255
+ },
+<trim>
+}
+```
+
+The overall configuratino is a dictionary with two keys, `sensors` and `zones`.
+Each of those is an array of entries.
+
+A sensor has a `name`, a `type`, a `readPath`, a `writePath`, a `minimum` value
+and an `maximum` value.
+
+The `name` is used to reference the sensor in the zone portion of the
+configuration.
+
+The `type` is the type of sensor it is. This influences how its value is
+treated. Supports values are: `fan`, `temp`, and `margin`.
+
+**TODO: Add further details on what the types mean.**
+
+The `readPath` is the path that tells the daemon how to read the value from this
+sensor. It is optional, allowing for write-only sensors. If the value is absent
+or `None` it'll be treated as a write-only sensor.
+
+If the `readPath` value contains: `/xyz/openbmc_project/extsensors/` it'll be
+treated as a sensor hosted by the daemon itself whose value is provided
+externally. The daemon will own the sensor and publish it to dbus. This is
+currently only supported for `temp` and `margin` sensor types.
+
+If the `readPath` value contains: `/xyz/openbmc_project/` (this is checked after
+external), then it's treated as a passive dbus sensor. A passive dbus sensor is
+one that listens for property updates to receive its value instead of actively
+reading the `Value` property.
+
+If the `readPath` value contains: `/sys/` this is treated as a directly read
+sysfs path. There are two supported paths:
+
+* `/sys/class/hwmon/hwmon0/pwm1`
+* `/sys/devices/platform/ahb/1e786000.pwm-tacho-controller/hwmon/<asterisk
+ asterisk>/pwm1`
+
+The `writePath` is the path to set the value for the sensor. This is only valid
+for a sensor of type `fan`. The path is optional. If can be empty or `None`. It
+then only supports two options.
+
+If the `writePath` value contains: `/sys/` this is treated as a directory
+written sysfs path. There are two support paths:
+
+* `/sys/class/hwmon/hwmon0/pwm1`
+* `/sys/devices/platform/ahb/1e786000.pwm-tacho-controller/hwmon/<asterisk
+ asterisk>/pwm1`
+
+If the `writePath` value contains: `/xyz/openbmc_project/control/fanpwm/` it
+sets of a sensor object that writes over dbus to the
+`xyz.openbmc_project.Control.FanPwm` interface. The `writePath` should end with
+the sensor's dbus name.
+
+**BUG NOTE** It's currently using the writePath specified for fanpwm as the
+sensor path, when in fact, the interface is attached to:
+
+```
+busctl introspect xyz.openbmc_project.Hwmon-1644477290.Hwmon1 /xyz/openbmc_project/sensors/fan_tach/fan1 --no-pager
+NAME TYPE SIGNATURE RESULT/VALUE FLAGS
+org.freedesktop.DBus.Introspectable interface - - -
+.Introspect method - s -
+org.freedesktop.DBus.Peer interface - - -
+.GetMachineId method - s -
+.Ping method - - -
+org.freedesktop.DBus.Properties interface - - -
+.Get method ss v -
+.GetAll method s a{sv} -
+.Set method ssv - -
+.PropertiesChanged signal sa{sv}as - -
+xyz.openbmc_project.Control.FanPwm interface - - -
+.Target property t 255 emits-change writable
+xyz.openbmc_project.Sensor.Value interface - - -
+.MaxValue property x 0 emits-change writable
+.MinValue property x 0 emits-change writable
+.Scale property x 0 emits-change writable
+.Unit property s "xyz.openbmc_project.Sensor.Value.Uni... emits-change writable
+.Value property x 2823 emits-change writable
+```
+
+The `minimum` and `maximum` values are optional. When `maximum` is non-zero it
+expects to write a percentage value converted to a value between the minimum and
+maximum.