xref: /openbmc/phosphor-fan-presence/docs/monitor/method.md (revision 64fb88c1bfd81e970b15f13938d59fc04d030b0f)
1# method
2
3## Description
4
5The method to use in monitoring a fan's functional state. One method can be
6configured per fan and each supported method requires its own set of attributes
7to be provided.
8
9## Attribute Value(s)
10
11Methods:
12
13- ["timebased"](#timebased) - Default
14- ["count"](#count)
15
16### "timebased"
17
18Uses timers for determining when a fan's sensor should be marked nonfunctional
19or functional after its been in that state for that continuous amount of time.
20Separate timers are used to transition a fan from functional to
21nonfunctional(`allowed_out_of_range_time`) and nonfunctional to
22functional(`functional_delay`).
23
24- `allowed_out_of_range_time` - Time(in seconds) that each fan sensor is allowed
25  to be calculated out of range of a current target before being marked
26  nonfunctional.
27- `functional_delay` - Optional, default = 0
28  - Time(in seconds) that each fan sensor must be calculated within range of a
29    current target before being marked functional.
30
31```text
32"method": "timebased",
33"allowed_out_of_range_time": 30,
34"functional_delay": 5
35```
36
37**Note: Since this method is the default, simply providing
38`allowed_out_of_range_time` and `functional_delay` attributes will result in
39this method being used.**
40
41- This is equivalent to above:
42
43  ```text
44  "allowed_out_of_range_time": 30,
45  "functional_delay": 5
46  ```
47
48### "count"
49
50An up/down counter for determining when a fan's sensor should be marked
51nonfunctional based on a `threshold` or functional when the counter = 0. Each
52fan sensor update where its feedback speed is calculated out of range of the
53current target increments the counter by 1. Once the counter reaches the
54`threshold`, the fan is marked nonfunctional. However, at any point the sensor's
55feedback speed is within range, the counter is decremented by 1. Therefore the
56fan's sensor(s) do not have to continuously be in a faulted state to be marked
57nonfunctional and instead is deemed nonfunctional once it accumulates the
58`threshold` number of times deemed out of range. The same is true for a
59nonfunctional fan sensor to become functional, where the counter must accumulate
60enough times deemed within range to decrement the counter to 0. This checking
61occurs at an interval dictated by the `count_interval` field.
62
63- `threshold` - Number of total times a fan sensor must be calculated out of
64  range before being marked nonfunctional.
65
66- `count_interval` - The interval, in seconds, to check the feedback speed and
67  increment/decrement the counter. Defaults to 1s if not present.
68
69```text
70"method": "count",
71"count_interval": 5,
72"sensors": [
73  {
74    "threshold": 30
75  }
76]
77```
78
79## Example
80
81```json
82{
83  "fans": [
84    {
85      "inventory": "/system/chassis/motherboard/fan0",
86      "allowed_out_of_range_time": 30,
87      "functional_delay": 5,
88      "deviation": 15,
89      "num_sensors_nonfunc_for_fan_nonfunc": 1,
90      "monitor_start_delay": 30,
91      "fan_missing_error_delay": 20,
92      "nonfunc_rotor_error_delay": 0,
93      "sensors": [
94        {
95          "name": "fan0_0",
96          "has_target": true
97        },
98        {
99          "name": "fan0_1",
100          "has_target": false,
101          "factor": 1.45,
102          "offset": -909
103        }
104      ]
105    },
106    {
107      "inventory": "/system/chassis/motherboard/fan1",
108      "method": "count",
109      "count_interval": 1,
110      "deviation": 15,
111      "num_sensors_nonfunc_for_fan_nonfunc": 1,
112      "monitor_start_delay": 30,
113      "fan_missing_error_delay": 20,
114      "nonfunc_rotor_error_delay": 0,
115      "sensors": [
116        {
117          "name": "fan0_0",
118          "has_target": true,
119          "threshold": 30
120        },
121        {
122          "name": "fan0_1",
123          "has_target": false,
124          "factor": 1.45,
125          "offset": -909,
126          "threshold": 30
127        }
128      ]
129    }
130  ]
131}
132```
133