OpenBMC makes it easy to add sensors for your hardware and is compliant with
the traditional Linux HWMon sensor format. The architecture of OpenBMC
sensors is to map sensors to D-Bus
objects. The D-Bus object will broadcast the PropertiesChanged
signal when either
the sensor or threshold value changes. It is the responsibility of other
applications to determine the effect of the signal on the system.
Service xyz.openbmc_project.Hwmon.Hwmon[x]
Path /xyz/openbmc_project/Sensors/<type>/<label>
Interfaces xyz.openbmc_project.Sensor.[*]
Signals: All properties for an interface will broadcast signal changed
Path definitions
<type> : The [HWMon class]
(https://www.kernel.org/doc/Documentation/hwmon/sysfs-interface) name in lower
case. Examples include temperature, fan, voltage
.
<label> : User defined
name of the sensor. Examples include ambient, cpu0, fan5
Sensor properties are standardized based on the type of sensor. A Threshold sensor contains specific properties associated with the rise and fall of a sensor value. The Sensor Interfaces are described in their respective YAML files. The path location in the source tree is identical to the interface being described below the phosphor-dbus-interfaces parent directory.
example: [openbmc/phosphor-dbus-interfaces/xyz/openbmc_project/Sensor/Threshold/Warning.yaml] (https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Sensor/Threshold/Warning.interface.yaml)
Maps to D-Bus interface
xyz.openbmc_project.Sensor.Threshold.Warning
Each 'name' property in the YAML file maps directly to D-Bus properties.
example:
[Warning.interface.yaml] (https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Sensor/Threshold/Warning.interface.yaml)
properties:
- name: WarningHigh
type: int64
- name: WarningLow
type: int64
- name: WarningAlarmHigh
type: boolean
- name: WarningAlarmLow
type: boolean
Maps to
busctl --system introspect xyz.openbmc_project.Hwmon.hwmon1 \
/xyz/openbmc_project/Sensors/temperature/ambient \
xyz.openbmc_project.Sensor.Threshold.Warning | grep property
.WarningAlarmHigh property b false emits-change writable
.WarningAlarmLow property b false emits-change writable
.WarningHigh property x 40000 emits-change writable
.WarningLow property x 10000 emits-change writable
"/xyz/openbmc_project/Sensors/temperature/ambient": {
"Scale": -3,
"Unit": "xyz.openbmc_project.Sensor.Value.Unit.DegreesC",
"Value": 30125,
"WarningAlarmHigh": 0,
"WarningAlarmLow": 0,
"WarningHigh": 40000,
"WarningLow": 10000
}
Any property value change broadcasts a signal on D-Bus. When a value trips past a threshold, an additional D-Bus signal is sent.
Example, if the value of WarningLow is 5...
From | To | propertyChanged Signals |
---|---|---|
1 | 5 | "xyz.org.openbmc_project.Sensor.Value" : value = 5 |
1 | 6 | "xyz.org.openbmc_project.Sensor.Value" : value = 6 , "xyz.org.openbmc_project.Sensor.Threshold.Warning" : WarningAlarmLow = 0 |
5 | 6 | "xyz.org.openbmc_project.Sensor.Value" : value = 6 |
6 | 1 | "xyz.org.openbmc_project.Sensor.Value" : value = 1 , "xyz.org.openbmc_project.Sensor.Threshold.Warning" : WarningAlarmLow = 1 |
On the BMC each sensor's configuration is located in a file. These files
can be found as a child of the /etc/default/obmc/hwmon
path.
There are two techniques to add a sensor to your system and which to use depends on if your system defines sensors via an MRW (Machine Readable Workbook) or not.
HWMon sensors are defined in the recipes-phosphor/sensor/phosphor-hwmon%
path within the machine configuration.
The children of the obmc/hwmon
directory should follow the children of the
devicetree/base
directory path on the system as defined by the kernel.
As an example, the Palmetto configuration file for the ambient temperature sensor.
recipes-phosphor/sensors/phosphor-hwmon%/obmc/hwmon/ahb/apb/i2c@1e78a000/i2c-bus@c0/[email protected]
which maps to this specific sensor and conf file on the system...
/sys/firmware/devicetree/base/ahb/apb/i2c@1e78a000/i2c-bus@c0/tmp423@4c
/etc/default/obmc/hwmon/ahb/apb/i2c@1e78a000/i2c-bus@c0/[email protected]
In order for the sensor to be exposed to D-Bus, the configuration file must describe the sensor attributes. Attributes follow a format.
xxx_yyy#=value
xxx = Attribute
# = Association number (i.e. 1-n)
yyy = HWMon sensor type (i.e. temp, pwm)
Attribute | Interfaces Added |
---|---|
LABEL | xyz.org.openbmc_project.Sensor.Value |
WARNHI, WARNLO | xyz.org.openbmc_project.Threshold.Warning |
CRITHI, CRITLO | xyz.org.openbmc_project.Threshold.Critical |
The HWMon sensor type
HWMon sensor type | type |
---|---|
temp | temperature |
in | voltage |
* | All other names map directly |
See the HWMon interface definitions for more definitions and keyword details
In this conf example the tmp423 chip is wired to two temperature sensors. The values must be described in 10-3 degrees Celsius.
LABEL_temp1=ambient
WARNLO_temp1=10000
WARNHI_temp1=40000
LABEL_temp2=cpu
WARNLO_temp2=10000
WARNHI_temp2=80000
With that level of system information, the sensor infrastructure code can provide all needed D-Bus properties.
Setting up sensor support with an MRW is done by adding a unit-hwmon-feature unit, for each hwmon feature needing to be monitored and then filling in the HWMON_FEATURE attribute. The XML field is required however a D-Bus interface will only be generated when the value property is not null. Values for Thresholds follow the HWMon format of no decimals. Temperature values must be described in 10-3 degrees Celsius. The HWMON_NAME will be used to derive the <type> while the DESCRIPTIVE_NAME creates the <label> for the instance path.
Field id | Value Required | Interfaces Added |
---|---|---|
HWMON_NAME | Y | xyz.org.openbmc_project.Sensor.Value |
WARN_LOW, WARN_HIGH | N | xyz.org.openbmc_project.Threshold.Warning |
CRIT_LOW, CRIT_HIGH | N | xyz.org.openbmc_project.Threshold.Critical |
Here is an example of a Fan sensor. If the RPMs go above 80000 or below 1000
addition signals will be sent over D-Bus. Note that neither CRIT_LOW or
CRIT_HIGH is set so xyz.org.openbmc_project.Threshold.Critical
will not be
added. The instance path will be /xyz/openbmc_project/Sensors/fan/fan0
.
<targetInstance>
<id>MAX31785.hwmon2</id>
<type>unit-hwmon-feature</type>
...
<attribute>
<id>HWMON_FEATURE</id>
<default>
<field><id>HWMON_NAME</id><value>fan1</value></field>
<field><id>DESCRIPTIVE_NAME</id><value>fan0</value></field>
<field><id>WARN_LOW</id><value>1000</value></field>
<field><id>WARN_HIGH</id><value>80000</value></field>
<field><id>CRIT_LOW</id><value></value></field>
<field><id>CRIT_HIGH</id><value></value></field>
</default>
</attribute>
Mailing List Comments on Sensor design