openUBMC Sensor Adaptation Guide ​

Overview ​

openUBMC sensor management is designed and implemented in accordance with the IPMI 2.0 protocol specification. The openUBMC design divides sensors into two main categories: continuous sensors and discrete sensors.

• Continuous Sensor: Also known as a threshold sensor, this sensor monitors quantifiable and continuously changing physical quantities such as temperature, voltage, current, and fan speed. The system represents sensor readings as analog values and compares them with preset thresholds to determine whether the monitored parameters are within the normal operating range.
• Discrete Sensor: Discrete sensors monitor discontinuous parameters and generally output discrete binary signals, such as "Present/Not Present" or "Normal/Faulty." These sensors do not provide specific quantitative values; their core functionality lies in state identification and event triggering, where the system implements alarm mechanisms by determining the status of the monitored object.

The following figure shows the relationship between configuration items. For mandatory elements during sensor configuration, see the following table:

Configuration Guidance ​

Sensor Entity Configuration ​

The sensor entity is the basis of subsequent configurations, so you must define entity objects first.

Configuring Properties ​

Key Configuration Points ​

1. Configure the Entity Id according to the table in the IPMI specification.
2. The Entity Instance must be unique for the same Entity Id. That is, the combination of ID and instance must uniquely identify a single entity.

Configuration Example ​

The following example describes how to add a sensor entity by using a fan. In the southbound management framework, entity objects interact with hardware through the Accessor/Scanner objects. Entity_Fan1 obtains the presence status and power-on/off status of the fan by synchronizing the values of Scanner_Fan1_Presence and Scanner_PowerGood. The system configures the following sensors in the CSR file of the fan board. The following example uses TaiShan 2280. The CSR file of the fan board is manifest/temp/build_openUBMC_debug_dev/conan_install/vpd/opt/bmc/sr/14100363_00000001050302035475.sr.

"Entity_FanBoard": {
    "Id": 11,
    "Instance": 117,    //Unique ID + instance
    "Name": "FanBoard${Slot}",
    "PowerState": 1,    // Power-on or power-off status
    "Presence": 1       // Presence status
},
"Entity_Fan1": {
    "Id": 30,
    "Instance": 96,
    "Name": "Fan1",
    "Presence": "<=/Scanner_Fan1_Presence.Value",
    "PowerState": "<=/Scanner_PowerGood.Value"
},
"Scanner_Fan1_Presence": { // For details about the scanner configuration, see Board Adaptation.
    "Chip": "#/Smc_FanBoardSMC",
    "Offset": 402656001,
    "Size": 1,
    "Mask": 1,
    "Type": 0,
    "Period": 2000,     // Scanning period
    "Debounce": "None", // Anti-jitter configuration
    "ScanEnabled": "<=/Scanner_PowerGood.Value",
    "NominalValue": 1,
    "@Default": {
        "ScanEnabled": 0
    },
    "Value": 0
},
"Scanner_PowerGood": {
    "Chip": "#/Smc_ExpBoardSMC",
    "Offset": 469765888,
    "Size": 1,
    "Mask": 255,
    "Type": 0,
    "Period": 100,
    "Debounce": "None",
    "Value": 0
},
"Smc_FanBoardSMC": {    // Defined according to the SMC specifications
    "Address": 96,
    "AddrWidth": 1,
    "OffsetWidth": 1,
    "WriteTmout": 0,
    "ReadTmout": 0
},

After the configuration is complete, verify whether Entity_FanBoard and Entity_Fan1 are successfully mounted to the resource collaboration interface.

> busctl --user tree bmc.kepler.sensor
...
├─/bmc/kepler/Systems
    │ └─/bmc/kepler/Systems/1
    ...
    ├─/bmc/kepler/Systems/1/Entities
    │   │ └─/bmc/kepler/Systems/1/Entities/Entity_FanBoard_0101
    │   │ └─/bmc/kepler/Systems/1/Entities/Entity_Fan1_0101
    ...

Threshold Sensor Configuration ​

Threshold sensors monitor quantifiable and continuously changing physical quantities such as temperature, voltage, current, and fan speed. The system represents readings as analog values and compares them with preset thresholds to determine whether the monitored parameters are within the normal operating range. The sensor class name is ThresholdSensor.

Configuring Properties ​

If necessary, you can select the following fields.

Key Configuration Points for Threshold Sensors ​

1. Set SensorType according to Table 42- SensorType Codes (P505) in the IPMI specifications.
2. The Mask properties must match the configured thresholds. If you configure a threshold, the corresponding bit of Mask must be set.
3. Note that the current Reading (that is, the raw value) cannot exceed 255. If it does, you must scale down the Reading using an expression and then restore it using the sensor expression formula. Generally, the actual values of data sources of sensors such as power and voltage sensors are likely to exceed the upper limit. You must convert these values to the int8 range. If the data range is not constrained and converted, the Reading value may not behave as expected.

Configuration Example ​

The following example uses a temperature sensor to describe how to configure a common threshold sensor, and uses a fan power sensor as an example to describe how to configure a threshold sensor that requires scaling. The system usually scales down the Reading value using the pipeline syntax. For details, see Expression syntax.

Non-Scaling Sensor ​

//Fan temperature sensor
"ThresholdSensor_FanBoardTemp": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_FanBoard.Id",
    "EntityInstance": "<=/Entity_FanBoard.Instance",
    "Initialization": 127, // Fixed value
    "Capabilities": 104,
    "SensorType": 1,
    "ReadingType": 1,
    "SensorName": "CLU${Slot} Temp",
    "AssertMask": 0, // Event generation mask
    "DeassertMask": 0, // Event recovery mask
    "ReadingMask": 0, // Reading value mask
    "Unit": 128, //Unit
    "BaseUnit": 1,
    "ModifierUnit": 0,
    "Linearization": 0, // Linear calculation equation parameter
    "M": 100, // Linear calculation equation parameter
    "RBExp": 224, // Linear calculation equation parameter
    "Analog": 1, // Linear calculation equation parameter
    "NominalReading": 0, // Nominal reading value of the sensor
    "NormalMaximum": 0,
    "NormalMinimum": 0,
    "MaximumReading": 127,
    "MinimumReading": 128,
    "Reading": "<=/Scanner_FanBrdTemp.Value",       // Raw read value
    "ReadingStatus": "≤/Scanner_FanBrdTemp.Status" // Read value status, configurable with expressions.
},
"Scanner_FanBrdTemp": {
    "Chip": "#/Smc_FanBoardSMC",
    "Size": 2,
    "Offset": 4865,
    "Mask": 65280,
    "Period": 2000,
    "Debounce": "None",
    "Value": 0,
    "Status": 0
}

Related property value ranges:

• AssertMask:
  
• DeassertMask:
  
• ReadingMask:
  
• Unit:
  
• Capabilities:
  

Scaling Sensor ​

//Fan power sensor
"ThresholdSensor_FanBoardPower": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_FanBoard.Id",
    "EntityInstance": "<=/Entity_FanBoard.Instance",
    "Initialization": 127,
    "Capabilities": 104,
    "SensorType": 11,
    "ReadingType": 1,
    "SensorName": "FanBoard${Slot} Power",
    "AssertMask": 0,
    "DeassertMask": 0,
    "ReadingMask": 0,
    "Unit": 0,
    "BaseUnit": 6,
    "ModifierUnit": 0,
    "Linearization": 0,
    "M": 5,
    "Analog": 1,
    "NominalReading": 0,
    "NormalMaximum": 0,
    "NormalMinimum": 0,
    "MaximumReading": 255,
    "MinimumReading": 0,
    "Reading": "≤/Scanner_Fan1_Pwr.Value |> expr($1 * 0.0002 / 5)", // You can scale the raw read value to the uint8 range using an expression.
    "ReadingStatus": "<=/Scanner_Fan1_Pwr.Status"
},
"Scanner_Fan1_Pwr": {
    "Chip": "#/Smc_FanBoardSMC",
    "Offset": 4864,
    "Size": 3,
    "Mask": 0,
    "Type": 1,
    "Value": 0,
    "Status": 0,
    "Period": 1000,
    "Debounce": "None"
}

The expr syntax scales the sensor Reading value so that it falls within the expected range. The service determines the specific scaling rules.

Conversion from the Raw Value to the Read Value for Threshold Sensors ​

The system converts the raw value of a threshold sensor to the read value using the following calculation formula. For details, see section 36.3 "Sensor Reading Conversion Formula" (P483) in the IPMI standard.

1. Properties involved in the conversion formula

2. Formula

• Two's complement: You must convert the property value to a signed number.

• The system converts the raw value into a read value according to the following formula:

  text

  temp = (M * x + B * 10<sup>K1</sup>) * 10<sup>K2</sup> <br>
  y = L(temp)

Example: M = 100, B = 3, K1 = 2, K2 = -2, ori_v = 200, L = 0x00 (linear expression, the calculated value is the actual value) Calculation result: y = (100 x ori_v + 3 x 100) x 0.01 = ori_v + 3 = 203

Definition and Conversion of Reading Status for Threshold Sensors ​

1. The reading status corresponds to the value of the Status property of the scanner.

2. Conversion between the read value status and conversion conditions

Discrete Sensor Configuration ​

Discrete sensors describe the discrete status of the hardware where the sensor is located, such as fan status or power status. They typically use discrete values like 0-Normal, 1-Faulty, 2-Unknown, and 3-NA for event alarms. The discrete sensor type is DiscreteSensor.

Configuring Properties ​

Key Configuration Points ​

1. Set SensorType according to the table in the IPMI specifications.
2. The ReadingType of a discrete sensor is 02h to 0Ch or 6Fh. You must set this property according to the configuration scenario of the discrete event.
3. The configuration of the discrete sensor is related to the mounted discrete event. The two parameters must match each other. The Mask properties must match the discrete event configuration.

Configuration Example ​

"DiscreteSensor_FAN1FPresence": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_Fan1.Id",
    "EntityInstance": "<=/Entity_Fan1.Instance",
    "Initialization": 99, // Fixed value
    "Capabilities": 64,
    "SensorType": 10,
    "ReadingType": 8,
    "SensorName": "FAN1 Presence",
    "DiscreteType": 0, // Discrete value mask
    "Unit": 192,
    "BaseUnit": 0,
    "ModifierUnit": 0,
    "RecordSharing": 1, // Sensor record sharing and discrete reference direction
    "Reading": 0, // This parameter is meaningless for discrete sensors and you do not need to set it.
    "SensorNumber": 255
}

Value range of the related properties:

• Capabilities:
  

Discrete Event Configuration ​

If you do not configure a discrete event for a discrete sensor, the BMC cannot manage the sensor. You usually configure discrete events in the software CSR.

Configuring Properties ​

Key Configuration Points ​

1. There is no requirement for the listening mode. You can select the listening mode as needed. If you select combined listening, ensure that you set the Property attribute as required and correctly configure the data of each byte according to the meaning. If you select independent listening, ensure that you correctly configure the three pieces of EventData data and EventDir properties according to the meaning.
2. The IPMI specifications define discrete events. Configure discrete events according to the descriptions and definitions in the IPMI specifications.

Configuration Example ​

The following example describes how to configure a fan presence event by using a fan presence sensor.

"DiscreteEvent_FAN1FPresence": {
    "Property": "<=/Scanner_Fan1_Presence.Value",
    "ListenType": 1, //Independent listening
    "EventData1": 0,
    "EventData2": 255,
    "EventData3": 255,
    "EventDir": "<=/Scanner_Fan1_Presence.Value",
    "Conversion": 1, //Event flip
    "SensorObject": "#/DiscreteSensor_FAN1FPresence" //Associate with the discrete sensor in the previous section.
}

After you complete the preceding configurations, the BMC can manage the FAN1 presence status, temperature, and power status. You can then proceed with commissioning.

Event Filter and Description Configuration ​

Before an event is reported, openUBMC filters it based on preset configurations (for example, to prevent frequent reporting of insignificant alarms). If the filter result is true, the system reports the event; if false, the system ignores it.

IpmiSelFilter and IpmiSelDesc serve as common mechanisms. For details about the design and implementation, see [sensor].

A sensor can report events only if they pass the event filtering criteria. The system ignores events that fail the filter and does not report them. Currently, openUBMC has developed 60 general IpmiSelFilters, which are stored in the proto/datas.yaml directory of the sensor repository. You can use the filters as required. If the existing filters do not meet the requirements, you must add new filters.

Configuring Properties ​

Configuration Example ​

t_ipmi_sel_filters: //The specific configuration is determined by the actual service.
  - FilterMask1: 0x0a94
    FilterMask2: 0xffff
    FilterMask3: 0xffff
    ReadingType: 0x01
    SensorType: 0x01

Configuring Properties ​

Configuration Example ​

t_ipmi_sel_descs:       //The specific configuration is determined by the actual service.
  - SensorType: 0xff
    ReadingType: 0x01
    SelData1: 0x00
    SelData2: 0xff
    SelData3: 0xff
    SelDesc: "Lower Non-critical going low"
    AlarmLevel: 1
    ShieldFlag: 0

Debugging Methods ​

You can check whether the sensor configuration is successful through package generation and board debugging. After building components, building the entire package, and upgrading the entire package by referring to [integrate_a_device], you can query the sensor using the following methods:

Web ​

The openUBMC WebUI provides threshold sensor query. Log in to the openUBMC WebUI, choose System > System Info > Sensor Info, and query the current threshold sensor.

IPMI ​

The openUBMC WebUI supports IPMI commands to query all sensors. You can run the sensor list command to query the information in in-band or out-of-band mode.

• In-band query: ipmitool sensor list
• Out-of-band query: ipmitool -I lanplus -H <host> -p 623 -U <username> -P <password> -C 17 sensor list

CLI ​

openUBMC supports CLI commands to query all sensors. Log in to openUBMC using SSH and run the ipmcget -t sensor -d list command.

Redfish ​

openUBMC supports Redfish interfaces for query. You can query the threshold sensor and discrete sensor using the GET request. Use the Postman tool to send the following requests to the test environment:

• Threshold sensor URI: redfish/v1/Chassis/:chassisid/ThresholdSensors
• Discrete sensor URI: redfish/v1/Chassis/:chassisid/DiscreteSensors

Sensor Adaptation FAQ Guide ​

Q01: Can sensors displayed by ipmitool sdr elist be sorted numerically by the sensor name? ​

Symptoms:

Current discrete sensors, for example, DIMMxxx, are not displayed in the numerical order of their names. The expectation is that DIMMs should be displayed in the order of DIMM000, DIMM001, DIMM010, and so on.

Solution:

The registration of sensor objects and corresponding SDR data is processed in the order of sensor CSR object distribution. The sequence in which the system distributes CSR objects to components cannot be guaranteed. To address this requirement, you can optimize the sensor object registration process in the sensor repository. The current registration process is as follows:

When the system distributes a sensor CSR object (on_add_object), it first caches the object (temp_store_sensor). After the system distributes all objects for a given position (on_add_object_complete), it handles the registration of sensors and SDRs collectively (register_sensors). You can optimize the register_sensors processing as follows:

-- Original Process
Step 1: Retrieve all cached sensor objects for the current position from the cache.
local pos_sensors = unregistered_sensors[position]
Step 2: Iterate through the sensor objects in pos_sensors and perform registration.

-- Optimized Process
Step 1: Retrieve all cached sensor objects for the current position from the cache.
local pos_sensors = unregistered_sensors[position]
Step 2: Sort pos_sensors based on the SensorName attribute of all sensor objects.
Step 3: Iterate through the sensor objects in pos_sensors and perform registration.

Q02: A new threshold sensor .sr file was added, but it is not displayed on the sensor page. How to analyze? ​

Solution:

1. Taking the board name openUBMC as an example, check if you added the new .sr file path to vpd/vendor/Huawei/Server/Kunpeng/openUBMC/profile.txt.
2. Check the Presence configuration in the Entity. If the attribute is 0, the system will not load the .sr file.
3. Check the PowerState configuration in the Entity. If the attribute is 0, the Entity becomes invalid, which causes the system to set the sensor Status to Disabled.
4. Check the Capabilities attribute in the ThresholdSensor. If bit 7 is set to 1, the sensor will be disabled if the Entity is invalid.
5. Check the ReadingStatus and Status attributes in the ThresholdSensor. If ReadingStatus is 0 or Status is Disabled, the sensor will not display a reading.

Q03: How to view sensor alarms via commands? ​

Solution:

Run the ipmitool sel list/elist command to view sensor alarms. Note that ipmcget -d sel -v list reads precise alarms, not sensor events, which correspond to system events on the Web page.

Q04: What are the methods for simulating discrete and threshold sensor alarms? ​

Solution:

You can use mdbctl setprop to modify the Value in the Scanner to trigger an alarm.
Command Description:

setprop <operation type> <object name> <interface name> <property name>

Parameter Description:

• operation type: Mandatory. Provides two modes: set and unset, representing setting a property value or clearing it.
• object name: Mandatory. The object to which the specified attribute interface belongs. You can use lsobj to query which objects the component has.
• interface name: Mandatory. The interface where the specified attribute is located. You can use lsprop to query which interfaces are attached to the object.
• property name: Mandatory. The specified attribute. You can use lsprop to query the attributes under the object.

Usage Example: Simulating an alarm for the threshold sensor Inlet Temp. It is known that the upper non-critical and upper critical thresholds for Inlet Temp are 41 and 43, respectively.

# The debug mode interface has been accessed and the hardware proxy module is connected.
% attach hwproxy
Success
# Check objects under Scanner
% lsobj Scanner
Scanner_Lm75_Inlet_0101
...
# Check the attributes of the Scanner_Lm75_Inlet_0101 object. Current Value is 29.
% lsprop Scanner_Lm75_Inlet_0101 
bmc.kepler.Object.Properties
  ClassName="Scanner"
  ObjectIdentifier=[1,"1","1","0101"]
  ObjectName="Scanner_Lm75_Inlet_0101"
  TraceSamplingRate=0
bmc.kepler.Scanner
  Status=0
  Value=29
bmc.kepler.Scanner.Aggregate
  AggregateOffset=0
  AggregateStatus=false
Private
  Chip="Lm75_InletTemp_0101"
  Debounce="MidAvg_Inlet_0101"
  FailureDebounceCount=10
  Mask=255
  NominalValue=0
  Offset=0
  Period=1000
  ScanEnabled=1
  Size=1
  SuccessDebounceCount=10
  Type=0
# Modify the Value of the Scanner to 50 to trigger an alarm.
% setprop set Scanner_Lm75_Inlet_0101 bmc.kepler.Scanner Value 50
Success
# Check the attributes of the Scanner_Lm75_Inlet_0101 object again. The Value has been successfully modified.
% lsprop Scanner_Lm75_Inlet_0101                                 
bmc.kepler.Object.Properties
  ClassName="Scanner"
  ObjectIdentifier=[1,"1","1","0101"]
  ObjectName="Scanner_Lm75_Inlet_0101"
  TraceSamplingRate=0
bmc.kepler.Scanner
  Status=0
  Value=50
bmc.kepler.Scanner.Aggregate
  AggregateOffset=0
  AggregateStatus=false
Private
  Chip="Lm75_InletTemp_0101"
  Debounce="MidAvg_Inlet_0101"
  FailureDebounceCount=10
  Mask=255
  NominalValue=0
  Offset=0
  Period=1000
  ScanEnabled=1
  Size=1
  SuccessDebounceCount=10
  Type=0

# Clear the setting and resume normal scanning to clear the alarm.
% setprop unset Scanner_Lm75_Inlet_0101 bmc.kepler.Scanner Value   
Success

Q05: What is the meaning of the discrete sensor status displayed on the Web page? ​

Solution:

Discrete Sensor Status Description:

• Disabled: Indicates that the current discrete sensor is disabled.
• 0xXXXX (for example, 0x8000) is defined according to the IPMI specification. It represents the current sensor status in hexadecimal. For specific meanings, please refer to the explanation of the Generic Offset field in Table 42-2 Generic Event/Reading Type Codes and the Sensor specific Offset field in Table 42-3 Sensor Type Codes in the IPMI specification.

Using DIMM000 as an example, a status value of 0x8040 means bit 6 is 1. Since the SensorType for DIMM000 is configured as 12 (0x0c) and ReadingType is 0x6f, according to the standard specification, a "Presence Detected" event has been generated.