xref: /openbmc/phosphor-power/phosphor-regulators/docs/sensor_monitoring.md (revision 8b38b177315d40f1f9bc1e4d0784d45ea17cbd5c) 
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- The chassis containing the regulator has an incorrect status, such as missing
44  or no input power.
45
46When regulator monitoring is disabled, the following changes will be made to all
47of the D-Bus sensor objects:
48
49- The Value property will be set to NaN.
50- The Available property will be set to false.
51
52## Error handling
53
54If an error occurs while reading the sensors for a voltage regulator rail:
55
56- The error will be logged. If the same error occurs repeatedly on a rail, it
57  will only be logged once per system boot.
58- Any remaining actions for the rail will be skipped.
59- The following changes will be made to all D-Bus sensor objects for this rail:
60  - The Value property will be set to NaN.
61  - The Functional property will be set to false.
62- Sensor monitoring will continue with the next rail or voltage regulator.
63- The sensors for this rail will be read again during the next monitoring cycle.
64
65If a subsequent attempt to read the sensors for the rail is successful, the
66following changes will be made to the D-Bus sensor objects:
67
68- The Value property will be set to the new sensor reading.
69- The Functional property will be set to true.
70