This section describes how to configure a sensor on openUBMC. A sensor is a type of hardware and belongs to the southbound management module. Its configurations comply with the CSR framework and syntax rules.

The sensor customization process includes configuring sensor entities, objects (threshold sensors and discrete sensors), sensor events, event filter, and event description. The following table describes their functions and configuration requirements.

Sensor Entity Configuration ​

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

Configuring Properties ​

Key Configuration Points ​

1. You are advised to configure the Entity Id according to the table in the IPMI specifications.
2. The Entity Instance must be unique with the same Entity Id. In other words, the combination of ID and instance must uniquely identify a single entity.

Configuration Example ​

The following uses the fan as an example to describe how to add a sensor entity. 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 following sensors are configured in the CSR file of the fan board. The following uses TaiShan 2280 as an example. 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 ​

Configuring Properties ​

If necessary, you can select the following fields.

Key Configuration Points ​

1. You are advised to set SensorType according to Table 42- SensorType Codes (P505) in the IPMI specifications.
2. The three Mask properties must match the configured thresholds. If a threshold is configured, 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, the Reading must be scaled down using an expression, and then restored 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. The values must be converted 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 uses the temperature sensor as an example to describe how to configure a common threshold sensor, and uses the fan power as an example to describe how to configure a threshold sensor that needs to be scaled down. The Reading value is usually scaled down using the pipeline syntax. For details, see Expression syntax.

1. Non-scaling sensor

   json

   //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, which is configurable with expressions.
   },
   "Scanner_FanBrdTemp": {
       "Chip": "#/Smc_FanBoardSMC",
       "Size": 2,
       "Offset": 4865,
       "Mask": 65280,
       "Period": 2000,
       "Debounce": "None",
       "Value": 0,
       "Status": 0
   }

   Value range of the related properties:

   • AssertMask: ! [image.png] (../../images/sensor_event/ThresholdSensor_AssertMask.png)
   • DeassertMask: ! [image.png] (../../images/sensor_event/ThresholdSensor_DeassertMask.png)
   • ReadingMask: ! [image.png] (../../images/sensor_event/ThresholdSensor_ReadingMask.png)
   • Unit: ![image.png] (../../images/sensor_event/ThresholdSensor_Unit.png)
   • Capabilities:

2. Scaling sensor

   json

   //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)", // The raw read value can be scaled 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's 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 raw value of a threshold sensor is converted 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: The property value needs to be converted to a signed number.

• The raw value is converted into a read value according to the following formula:

  temp = (M * x + B * 10^K1) * 10^K2
  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 ​

Configuring Properties ​

Key Configuration Points ​

1. You are advised to set SensorType according to the table in the IPMI specifications.
2. The ReadingType of a discrete sensor is 02h to 0Ch or 6Fh. You need to 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 three masks 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 does not need to be set.
    "SensorNumber": 255
}

Value range of the related properties:

• Capabilities:
  

Discrete Event Configuration ​

If no discrete event is configured for a discrete sensor, the sensor cannot be managed by the BMC. Discrete events are usually configured in the software CSR.

Configuring Properties ​

Key Configuration Points ​

1. There is no requirement on the listening mode. You can select the listening mode as needed. If the combined listening is selected, ensure that the Property property is set as required and the data of each byte is correctly configured according to the meaning. If the independent listening is selected, ensure that the three pieces of EventData data and EventDir properties are correctly configured according to the meaning.
2. Discrete events are defined by the IPMI specifications. You are advised to configure discrete events according to the descriptions and definitions in the IPMI specifications.

Configuration Example ​

The following uses the fan presence sensor as an example to describe how to configure a fan presence event.

"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 the preceding configurations are complete, the BMC can manage the FAN1 presence status, temperature, and power status. You can then proceed with the commissioning.

IpmiSelFilter Event Filter Configuration ​

IpmiSelFilter and IpmiSelDesc are used 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. Events that fail the filter are ignored and not reported. 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 need to 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

IpmiSelDesc Event Description Configuration ​

IpmiSelDesc refers to the level and description of the event reported by the sensor. The object definition is the same as that of IpmiSelFilter. IpmiSelDesc is stored in the proto/datas.yaml in the sensor repository, and the model definition is stored in the mds/model.json file in the sensor repository. For details, see the source code.

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

Commissioning Methods ​

You can check whether the sensor configuration is successful through package generation and board commissioning. After building components, building the entire package, and upgrading the entire package by referring to integrate_a_device, you can query the sensor in any of the following four ways:

• 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

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

  ![image.png] (../../images/sensor_event/Sensor_CLI.png)

• Redfish

  The 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 ![image.png] (../../images/sensor_event/Sensor_Redfish1.png)
  • Discrete sensor URI: redfish/v1/Chassis/:chassisid/DiscreteSensors ![image.png] (../../images/sensor_event//Sensor_Redfish2.png)