xref: /openbmc/docs/designs/virtual-sensors.md (revision 37055f7d) 
1### Virtual sensors
2
3Author:
4  Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
5
6Created:
7  2020-05-13
8
9## Problem Description
10There are some sensors in the system whose values are derived from actual
11sensor data and some other factor like fan speed for temperature
12sensors, some complex and non standard scale factors or some other algorithmic
13calculations. Some of Virtual sensor examples are:
14
151. Airflow: Function of Fan RPM reported in units of cubic-feet per second.
162. Voltage delta between two ADC inputs. When the actual diff is what which
17   should not cross a threshold.
183. Power consumption when we have Energy/time.
19
20This design will allow to generate a new virtual sensors which are defined to
21be specific manipulation/function of existing sensors.
22
23## Background and References
24None.
25
26## Requirements
27This should implement a new virtual sensor for every given sensor and update
28them as per changes in existing sensors.
29This implementation should provide
30- a daemon to create and monitor each sensor defined in config file and
31  update them based on value change in each given sensor.
32- Every virtual sensor will be waiting for event for change in dbus value of
33  each sensor parameter and will update this sensor.
34- Sensor parameter can be any sensor dbus path and it also supports
35  chaining of virtual sensors.
36- a dbus interface like other sensors to allow other services to access its
37  data
38- capability to read parameter details from config file
39- capability to read a algorithm string from config file and use the same
40  algorithm in calculating value for new virtual sensor
41
42## Proposed Design
43Create a D-bus service "xyz.openbmc_project.VirtualSensor" with object paths
44for each sensor: "/xyz/openbmc_project/sensor/temperature/sensor_name"
45
46There is a JSON configuration file for name, old path and algorithm.
47For example,
48
49```json
50  {
51    "Desc" :
52    {
53        "Name" : "Virtual_Inlet_Temp",
54        "SensorType" : "temperature"
55    },
56    "Params":
57    {
58      "ConstParam" :
59      [
60        {
61          "ParamName" : "P1",
62          "Value" : 1.1
63        }
64      ],
65      "DbusParam" :
66      [
67        {
68          "ParamName" : "P2",
69          "Desc" :
70          {
71              "Name" : "MB_INLET_TEMP",
72              "SensorType" : "temperature"
73          }
74        },
75        {
76          "ParamName" : "P3",
77          "Desc" :
78          {
79            "Name" : "MB_FAN0_TACH",
80            "SensorType" : "fan_tach"
81          }
82        }
83      ]
84    },
85    "Expression": "P1 + P2 + 5 - P3 * 0.1",
86    "Thresholds":
87    {
88      "CriticalHigh": 90,
89      "CriticalLow": 20,
90      "WarningHigh": 70,
91      "WarningLow": 30
92    }
93  }
94
95Desc:       It defines name and unit of a sensor. Main Desc object defines
96            details about new virtual sensor and inside DbusParam object,
97            it defines details about existing dbus sensors.
98Name:       Name of virtual sensor
99SensorType: Unit type of sensors and supported
100Expression: An algorithm to be used to calculate sensor value
101Params:     There are currently 2 types of parameter supported ConstParam
102            and DbusParam. Every pamas should have a name to be reffered
103            in expression
104ConstParam: This is a parameter which has a constant value defined here
105DbusParam:  This is an existing/virtual sensor which is listed in dbus and
106            it's value can be read from dbus path
107Thresholds: It has critical and warning high/low value to monitor sensor
108            value and used as per sensor interface defined in
109            phosphor-dbus-interfaces.
110
111```
112## Alternatives Considered
113None
114
115## Impacts
116This application is monitoring existing sensors whenever they change values
117then only it will update this sensors so impact should be very minimal.
118
119## Testing
120Testing can be done by monitoring data read from dbus interface over a period
121of time and also can see these data if it changes by comparing with given
122sensors.
123