xref: /openbmc/docs/designs/virtual-sensors.md (revision 09f0c0e6) 
1### Virtual sensors
2
3Author:
4  Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
5
6Primary assignee:
7  Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
8
9Created:
10  2020-05-13
11
12## Problem Description
13There are some sensors in the system whose values are derived from actual
14sensor data and some other factor like fan speed for temperature
15sensors, some complex and non standard scale factors or some other algorithmic
16calculations. Some of Virtual sensor examples are:
17
181. Airflow: Function of Fan RPM reported in units of cubic-feet per second.
192. Voltage delta between two ADC inputs. When the actual diff is what which
20   should not cross a threshold.
213. Power consumption when we have Energy/time.
22
23This design will allow to generate a new virtual sensors which are defined to
24be specific manipulation/function of existing sensors.
25
26## Background and References
27None.
28
29## Requirements
30This should implement a new virtual sensor for every given sensor and update
31them as per changes in existing sensors.
32This implementation should provide
33- a daemon to create and monitor each sensor defined in config file and
34  update them based on value change in each given sensor.
35- Every virtual sensor will be waiting for event for change in dbus value of
36  each sensor parameter and will update this sensor.
37- Sensor parameter can be any sensor dbus path and it also supports
38  chaining of virtual sensors.
39- a dbus interface like other sensors to allow other services to access its
40  data
41- capability to read parameter details from config file
42- capability to read a algorithm string from config file and use the same
43  algorithm in calculating value for new virtual sensor
44
45## Proposed Design
46Create a D-bus service "xyz.openbmc_project.VirtualSensor" with object paths
47for each sensor: "/xyz/openbmc_project/sensor/temperature/sensor_name"
48
49There is a JSON configuration file for name, old path and algorithm.
50For example,
51
52```json
53  {
54    "Name": "Virtual_Inlet_Temp",
55    "Algo": "P1 + P2 + 5 - P3 * 0.1",
56    "Params":
57    {
58      "P1": "/xyz/openbmc_project/sensor/temperature/"Inlet_Temp",
59      "P2": "/xyz/openbmc_project/sensor/fan/fan_0",
60      "P3": "200"
61    },
62    "Thresholds":
63    {
64	"CriticalHigh": 90,
65	"CriticalLow": 20,
66	"WarningHigh": 70,
67	"WarningLow": 30
68    }
69  }
70
71Name:       Name of virtual sensor
72Algo:       An algorithm to be used to calculate value
73Params:     It can be an existing/virtual sensor dbus path to read value or it
74            can be a value to be used in calculation
75Thresholds: It has critical and warning high/low value to monitor sensor
76            value and used as per sensor interface defined in
77            phosphor-dbus-interfaces.
78
79```
80## Alternatives Considered
81None
82
83## Impacts
84This application is monitoring existing sensors whenever they change values
85then only it will update this sensors so impact should be very minimal.
86
87## Testing
88Testing can be done by monitoring data read from dbus interface over a period
89of time and also can see these data if it changes by comparing with given
90sensors.
91