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