xref: /openbmc/dbus-sensors/README.md (revision 8b34f2c9) 
1# dbus-sensors
2
3dbus-sensors is a collection of sensor applications that provide the
4xyz.openbmc_project.Sensor collection of interfaces. They read sensor values
5from hwmon, d-bus, or direct driver access to provide readings. Some advance
6non-sensor features such as fan presence, pwm control, and automatic cpu
7detection (x86) are also supported.
8
9## key features
10
11- runtime re-configurable from d-bus (entity-manager or the like)
12
13- isolated: each sensor type is isolated into its own daemon, so a bug in one
14  sensor is unlikely to affect another, and single sensor modifications are
15  possible
16
17- async single-threaded: uses sdbusplus/asio bindings
18
19- multiple data inputs: hwmon, d-bus, direct driver access
20
21## dbus interfaces
22
23A typical dbus-sensors object support the following dbus interfaces:
24
25```text
26Path        /xyz/openbmc_project/sensors/<type>/<sensor_name>
27
28Interfaces  xyz.openbmc_project.Sensor.Value
29            xyz.openbmc_project.Sensor.Threshold.Critical
30            xyz.openbmc_project.Sensor.Threshold.Warning
31            xyz.openbmc_project.State.Decorator.Availability
32            xyz.openbmc_project.State.Decorator.OperationalStatus
33            xyz.openbmc_project.Association.Definitions
34
35```
36
37Sensor interfaces collection are described
38[here](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Sensor).
39
40Consumer examples of these interfaces are
41[Redfish](https://github.com/openbmc/bmcweb/blob/master/redfish-core/lib/sensors.hpp),
42[Phosphor-Pid-Control](https://github.com/openbmc/phosphor-pid-control),
43[IPMI SDR](https://github.com/openbmc/phosphor-host-ipmid/blob/master/dbus-sdr/sensorcommands.cpp).
44
45## Reactor
46
47dbus-sensor daemons are [reactors](https://github.com/openbmc/entity-manager)
48that dynamically create and update sensors configuration when system
49configuration gets updated.
50
51Using asio timers and async calls, dbus-sensor daemons read sensor values and
52check thresholds periodically. PropertiesChanged signals will be broadcasted for
53other services to consume when value or threshold status change. OperationStatus
54is set to false if the sensor is determined to be faulty.
55
56A simple sensor example can be found
57[here](https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md).
58
59## configuration
60
61Sensor devices are described using Exposes records in configuration file. Name
62and Type fields are required. Different sensor types have different fields.
63Refer to entity manager
64[schema](https://github.com/openbmc/entity-manager/blob/master/schemas/legacy.json)
65for complete list.
66
67## sensor documentation
68
69- [ExternalSensor](https://github.com/openbmc/docs/blob/master/designs/external-sensor.md)
70  virtual sensor
71
72## Sensor Type Documentation
73
74### ADC Sensors
75
76ADC sensors are sensors based on an Analog to Digital Converter. They are read
77via the Linux kernel Industrial I/O subsystem (IIO).
78
79One of the more common use cases within OpenBMC is for reading these sensors
80from the ADC on the Aspeed ASTXX cards.
81
82To utilize ADC sensors feature within OpenBMC you must first define and enable
83it within the kernel device tree.
84
85When using a common OpenBMC device like the AST2600 you will find a "adc0" and
86"adc1" section in the aspeed-g6.dtsi file. These are disabled by default so in
87your system-specific dts you would enable and configure what you want with
88something like this:
89
90```text
91iio-hwmon {
92    compatible = "iio-hwmon";
93    io-channels = <&adc0 0>;
94    ...
95}
96
97&adc0 {
98    status = "okay";
99    ...
100};
101
102&adc1 {
103    status = "okay";
104    ...
105};
106```
107
108**Note** that this is not meant to be an exhaustive list on the nuances of
109configuring a device tree but really to point users in the general direction.
110
111You will then create an entity-manager configuration file that is of type "ADC"
112A very simple example would like look this:
113
114```text
115            "Index": 0,
116            "Name": "P12V",
117            "PowerState": "Always",
118            "ScaleFactor": 1.0,
119            "Type": "ADC"
120```
121
122When your system is booted, a "in0_input" file will be created within the hwmon
123subsystem (/sys/class/hwmon/hwmonX). The adcsensor application will scan d-bus
124for any ADC entity-manager objects, look up their "Index" value, and try to
125match that with the hwmon inY_input files. When it finds a match it will create
126a d-bus sensor under the xyz.openbmc_project.ADCSensor service. The sensor will
127be periodically updated based on readings from the hwmon file.
128