xref: /openbmc/phosphor-power/phosphor-regulators/docs/sensor_monitoring.md (revision 80689db1ed2f4677bd3ea3fc3b74f26900bf44d9) 
1# Sensor Monitoring
2
3## Overview
4
5Sensor values such as output voltage, output current, and temperature can be
6read from some voltage regulators. Sensor values are measured, actual values
7rather than target values.
8
9When [regulator monitoring](monitoring.md) is enabled, the `phosphor-regulators`
10application reads sensor values once per second.
11
12The sensor values are stored on D-Bus on the BMC, making them available to
13external interfaces like Redfish.
14
15## How sensor monitoring is defined
16
17Sensor monitoring is defined for a voltage regulator using the
18[sensor_monitoring](config_file/sensor_monitoring.md) object in the
19[JSON config file](config_file/README.md).
20
21This object specifies actions to run, such as
22[pmbus_read_sensor](config_file/pmbus_read_sensor.md).
23
24## How sensors are stored on D-Bus
25
26The first time a sensor value is read, a corresponding sensor object is created
27on D-Bus. On subsequent reads, the existing D-Bus sensor object is updated with
28the new sensor value.
29
30The D-Bus sensor object implements the following interfaces:
31
32- xyz.openbmc_project.Sensor.Value
33- xyz.openbmc_project.State.Decorator.OperationalStatus
34- xyz.openbmc_project.State.Decorator.Availability
35- xyz.openbmc_project.Association.Definitions
36
37An existing D-Bus Sensor object is removed from D-Bus if no corresponding sensor
38values are read during monitoring. This can occur in the following cases:
39
40- The regulator has been removed from the system (no longer present).
41- The regulator was replaced, and the new regulator supports a different set of
42  sensors values. For example, temperature_peak is no longer provided.
43
44When regulator monitoring is disabled, the following changes will be made to all
45of the D-Bus sensor objects:
46
47- The Value property will be set to NaN.
48- The Available property will be set to false.
49
50## Error handling
51
52If an error occurs while reading the sensors for a voltage regulator rail:
53
54- The error will be logged. If the same error occurs repeatedly on a rail, it
55  will only be logged once per system boot.
56- Any remaining actions for the rail will be skipped.
57- The following changes will be made to all D-Bus sensor objects for this rail:
58  - The Value property will be set to NaN.
59  - The Functional property will be set to false.
60- Sensor monitoring will continue with the next rail or voltage regulator.
61- The sensors for this rail will be read again during the next monitoring cycle.
62
63If a subsequent attempt to read the sensors for the rail is successful, the
64following changes will be made to the D-Bus sensor objects:
65
66- The Value property will be set to the new sensor reading.
67- The Functional property will be set to true.
68