1# Sensor Config
2
3This program is only meant to control fans given thermal sensor readings.
4
5All sensors in phosphor-dbus-interfaces for OpenBMC use Sensor.Value as their
6accessor.  This provides read-only access to information.  The goal of the
7configuration is to specify how it can be read and if it's a fan, how the PID
8output can be written.  Initially there'll only be sysfs and passive dbus
9access.  If a writePath for a sensor is a dbus path, then the system will need
10to verify which Control.Fan* interfaces is registered and send values to the
11Target property of that interface.
12
13The min/max specified are to range a writePercent to the sensor.  The current
14FanController object outputs the new fan speed goal as a PWM percentage.  Other
15fan PID control objects may not, and they can leave the fields as 0 & 0.
16
17The only requirement for a sensor is that it isn't writeonly.  Only fans are
18expected to have a writePath set, and in this current version non-fan sensors
19are assumed readonly.
20
21The sensor names are unique across all zones.
22
23"sensors" : [
24  {
25    "name": "fan1",  /* Name of the sensor. */
26    "type": "fan",   /* Type of sensor, fan, temp, margin */
27    "readPath": "",  /* How the sensor can be read[1] */
28    "writePath": "", /* How the sensor can be set[2] */
29    "min": 0,        /* The minimum value used for scaling writes (int64) */
30    "max": 255,      /* The maximum value used for scaling writes (int64) */
31    "timeout": 0     /* The timeout value for the sensor, used for failsafe, 0
32                      * means no timeout (int64) */
33  },
34]
35
36[1] readPath has multiple options:
37* If it has "/xyz/openbmc_project/extsensors/" in it, it's an EXTERNAL or
38  host-provided sensor.
39* If it has "/xyz/openbmc_project/" in it, it's a sensor whose value is
40  received passively over dbus.
41* If it has "/sys/" in it, it's a sensor read directly from sysfs.
42
43[2]
44* This can be left blank if the sensor is read-only.
45* If it has "/sys/" in it, it's a sensor written to sysfs.
46  * If min and max are non-zero, it'll convert the value to within the range.
47    and output that modified value.  So, if it receives a value of .90 and min
48    is 0, and max is 255, it'll convert that to a value of 229.5 that is then
49    cast to int64_t.
50
51# PID Config
52
53The PID configuration is a list of PIDs per zone.
54
55"zones" : [
56  {
57    "id": 1, /* zone id. */
58    "minThermalRpm": 3000.0, /* The minimum thermal RPM value. (double) */
59    "failsafePercent": 75.0, /* The percent to use when the zone is in fail-safe mode. (double) */
60    "pids": [
61      {
62        "name": "fan1-5",           /* PID name */
63        "type": "fan",              /* Type of PID, fan, temp, or margin. */
64        "inputs": ["fan1", "fan5"], /* Sensor names that are inputs for the PID */
65        "setpoint": 90.0,           /* For temp/margin PIDs this is the setpoint, ignored otherwise (double) */
66        "pid": {
67          "samplePeriod": 0.1,          /* The input sample period. (double) */
68          "proportionalCoeff": 0.0,     /* The proportional coefficient. (double) */
69          "integralCoeff": 0.0,         /* The integral coefficient. (double) */
70          "feedFwdOffOffsetCoeff": 0.0, /* The feed-forward offset coefficient. (double) */
71          "feedFwdGainCoeff": 0.010,    /* The feed-forward gain coefficient. (double) */
72          "integralLimit_min": 0.0,     /* The integral limit clamp, min, max (double) */
73          "integralLimit_max": 0.0,
74          "outLim_min": 30.0,           /* the PID output clamp, min, max (double) */
75          "outLim_max": 100.0,
76          "slewNeg": 0.0, /* The slew negative value. (double) */
77          "slewPos": 0.0  /* The slew positive value. (double) */
78        }
79      }
80    ]
81  }
82]
83