本文主要从新手的角度出发，描述如何基于 openUBMC 配置一个传感器。传感器作为一种硬件，归属于南向管理模块，配置内容均遵循 CSR 框架和语法规则。

传感器定制流程包括传感器Entity配置、对象配置（门限传感器配置、离散传感器配置）、传感器事件配置、事件过滤配置和事件描述配置，它们的作用和配置要求如下表。下面将对这些配置项进行详细介绍。

Entity 传感器实体配置 ​

传感器实体是后续配置的基础，配置传感器时应当优先定义实体对象。

配置属性 ​

配置关键点 ​

1. Entity Id建议按照IPMI规范中的表格进行配置。
2. Entity Instance 保证同一 Entity Id 下唯一，即确保 id+instance 能够唯一确定一个实例。

配置示例 ​

下面以风扇为例，展示如何新增一个传感器实体。在南向管理框架中，实体对象是通过Accessor/Scanner对象与硬件交互的，如下所示， Entity_Fan1 是通过同步 Scanner_Fan1_Presence 和 Scanner_PowerGood 的Value值来获得风扇的在位状态和上下电状态的。下列传感器配置在风扇板的CSR文件中，以TaiShan2280为例，风扇板对应的CSR文件为 manifest/temp/build_openUBMC_debug_dev/conan_install/vpd/opt/bmc/sr/14100363_00000001050302035475.sr。

"Entity_FanBoard": {
    "Id": 11,
    "Instance": 117,    // id + instance全局唯一
    "Name": "FanBoard${Slot}",
    "PowerState": 1,    // 上下电状态
    "Presence": 1       // 在位状态
},
"Entity_Fan1": {
    "Id": 30,
    "Instance": 96,
    "Name": "Fan1",
    "Presence": "<=/Scanner_Fan1_Presence.Value",
    "PowerState": "<=/Scanner_PowerGood.Value"
},
"Scanner_Fan1_Presence": {  // Scanner配置参考《板卡适配》
    "Chip": "#/Smc_FanBoardSMC",
    "Offset": 402656001,
    "Size": 1,
    "Mask": 1,
    "Type": 0,
    "Period": 2000,     // scanner扫描周期
    "Debounce": "None", // 防抖配置
    "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": {    // 根据SMC规范定义
    "Address": 96,
    "AddrWidth": 1,
    "OffsetWidth": 1,
    "WriteTmout": 0,
    "ReadTmout": 0
},

配置完成后，出包验证资源协作接口上是否成功挂载了Entity_FanBoard和 Entity_Fan1。

> 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
    ...

ThresholdSensor 门限传感器配置 ​

配置属性 ​

若有特殊需要，可以选配下列字段。

配置关键点 ​

1. 传感器类型 SensorType 建议按照IPMI规范中的 Table 42-, Sensor Type Codes(P505) 配置。
2. 三个 Mask属性要与配置的门限匹配，若配置了某个门限，Mask相应bit需要置位
3. 注意当前 Reading（也即原始值），数据源的范围不可超过 255，若不满足则需要通过表达式进行一定程度的缩放，并通过传感器的表达公式进行还原。一般情况下，功率、电压等传感器的数据源实际值容易出现数值越界的情况，需要转换到int8范围内。若不进行数据范围限制和转换，Reading可能不符合预期。

配置示例 ​

下面以温度传感器为例展示普通门限传感器配置方法，以风扇功率为例展示需要缩放的门限传感器配置方法。其中 Reading 缩放一般采用管道语法实现，可参考表达式语法。

1. 非缩放传感器

   json

   // 风扇温度传感器
   "ThresholdSensor_FanBoardTemp": {
       "OwnerId": 32,
       "OwnerLun": 0,
       "EntityId": "<=/Entity_FanBoard.Id",
       "EntityInstance": "<=/Entity_FanBoard.Instance",
       "Initialization": 127,      // 门限传感器固定取值
       "Capabilities": 104,
       "SensorType": 1,
       "ReadingType": 1,
       "SensorName": "CLU${Slot} Temp",
       "AssertMask": 0,        // 事件产生掩码
       "DeassertMask": 0,      // 事件恢复掩码
       "ReadingMask": 0,       // 读值掩码
       "Unit": 128,            // 单位
       "BaseUnit": 1,
       "ModifierUnit": 0,
       "Linearization": 0,     // 线性计算方程参数
       "M": 100,               // 线性计算方程参数
       "RBExp": 224,           // 线性计算方程参数
       "Analog": 1,            // 线性计算方程参数
       "NominalReading": 0,    // 传感器名义读值
       "NormalMaximum": 0,
       "NormalMinimum": 0,
       "MaximumReading": 127,
       "MinimumReading": 128,
       "Reading": "<=/Scanner_FanBrdTemp.Value",       // 原始读值
       "ReadingStatus": "<=/Scanner_FanBrdTemp.Status" // 读值状态，可配置表达式
   },
   "Scanner_FanBrdTemp": {
       "Chip": "#/Smc_FanBoardSMC",
       "Size": 2,
       "Offset": 4865,
       "Mask": 65280,
       "Period": 2000,
       "Debounce": "None",
       "Value": 0,
       "Status": 0
   }

   相关属性取值范围：

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

2. 缩放传感器

   json

   // 风扇功率传感器
   "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)",    // 原始读值可通过表达式缩放至uint8取值范围内
       "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"
   }

   该传感器对象 Reading 字段读值缩放使用了 expr 语法，保证数据范围在预期内，具体的缩放规则由业务侧决定。

门限传感器原始值到读值的转换 ​

门限传感器的原始值到读值通过计算公式进行转换，具体如下，参考IPMI标准规范36.3 Sensor Reading Conversion Formula(P483)。

1、转换公式涉及的属性

2、计算公式

• 二补数：即补码，也就是需要先将属性值转化为有符号数

• 按以下计算公式，将原始值转换成读值

  temp = (M * x + B * 10^K1) * 10^K2
  y = L(temp)

示例：M = 100，B = 3，K1 = 2，K2 = -2，ori_v = 200，L = 0x00 (线性表达式，计算出来是多少即是多少) 计算结果为：y = (100 * ori_v + 3 * 100) * 0.01 = ori_v + 3 = 203

门限传感器读值状态(ReadingStatus)定义及转换 ​

1、读值状态与Scanner的Status属性取值的含义对应

2、可支持的读值状态之间的转换及转换条件

DiscreteSensor 离散传感器配置 ​

配置属性 ​

配置关键点 ​

1. 传感器类型 SensorType 建议按照IPMI规范中的表格配置。
2. 离散传感器的读值类型 ReadingType分为两种：02h~0Ch、6Fh，需要根据离散事件的配置场景相应配置该属性。
3. 离散传感器的配置与挂载的离散事件相关，二者应当相互配合，注意三个 Mask 的配置需要与离散事件配置匹配。

配置示例 ​

"DiscreteSensor_FAN1FPresence": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_Fan1.Id",
    "EntityInstance": "<=/Entity_Fan1.Instance",
    "Initialization": 99,       // 离散传感器固定取值
    "Capabilities": 64,
    "SensorType": 10,
    "ReadingType": 8,
    "SensorName": "FAN1 Presence",
    "DiscreteType": 0,          // 离散值掩码
    "Unit": 192,
    "BaseUnit": 0,
    "ModifierUnit": 0,
    "RecordSharing": 1,         // 传感器记录共享、离散参考方向
    "Reading": 0,               // 此参数在离散传感器中无实际意义，一般无需配置
    "SensorNumber": 255
}

相关属性取值范围：

• Capabilities：
  

DiscreteEvent 离散事件配置 ​

对于离散传感器来说，如果不配置离散事件，那该传感器就不能被 BMC 管理。离散事件一般配置在软件CSR中。

配置属性 ​

配置关键点 ​

1. 监听方式无固定要求，可以根据场景任意选择。若选择组合监听，需要保证 Property属性按要求进行配置，保证各个字节的数据皆按照含义正确配置；若选择独立监听，需要保证三个EventData数据及EventDir属性按照含义正确配置。
2. 离散事件是遵循IPMI规范定义的，因此建议参照IPMI规范中的描述和定义进行配置。

配置示例 ​

以风扇在位传感器为例，下面将为其配置一个风扇在位事件。

"DiscreteEvent_FAN1FPresence": {
    "Property": "<=/Scanner_Fan1_Presence.Value",
    "ListenType": 1,    // 独立监听
    "EventData1": 0,
    "EventData2": 255,
    "EventData3": 255,
    "EventDir": "<=/Scanner_Fan1_Presence.Value",
    "Conversion": 1,    // 事件翻转
    "SensorObject": "#/DiscreteSensor_FAN1FPresence"    // 关联上一小节的离散传感器
}

上述内容配置完成后，BMC就可以管理FAN1在位状态和温度、功率状态，可以进入调测步骤。

IpmiSelFilter 事件过滤配置 ​

IpmiSelFilter 和 IpmiSelDesc 作为公共机制，具体设计与实现参见《sensor》。

传感器能否上报事件还需要经过事件过滤，能成功过滤则能够上报事件，若不需要上报事件则忽略。当前 openUBMC 已开发了60个通用性较强的 IpmiSelFilter，位于 sensor 仓库中的 proto/datas.yaml 路径下，用户可按需取用，若现有过滤器不满足需求则需要自行新增。

配置属性 ​

配置示例 ​

t_ipmi_sel_filters:     // 具体配置由实际业务决定
  - FilterMask1: 0x0a94
    FilterMask2: 0xffff
    FilterMask3: 0xffff
    ReadingType: 0x01
    SensorType: 0x01

IpmiSelDesc 事件描述配置 ​

传感器上报事件的等级及描述。这类对象的定义与IpmiSelFilter相同，位于 sensor 仓库中的 proto/datas.yaml 路径下，模型定义位于 sensor 仓库中的 mds/model.json 中，可参考源码深入了解。

配置属性 ​

配置示例 ​

t_ipmi_sel_descs:       // 具体配置由实际业务决定
  - SensorType: 0xff
    ReadingType: 0x01
    SelData1: 0x00
    SelData2: 0xff
    SelData3: 0xff
    SelDesc: "Lower Non-critical going low"
    AlarmLevel: 1
    ShieldFlag: 0

调测方法 ​

传感器定制可以通过出包+上板调测的方式来验证是否成功。参考《适配一款硬件》 完成组件构建、整包构建、整包升级后，可通过以下 4 种方式查询传感器。

• Web

  openUBMC Web 提供了门限传感器查询。Web 登录 openUBMC 后，【系统管理】 -> 【系统信息】-> 【传感器】，即可查询当前的门限传感器。

• IPMI

  openUBMC 支持 IPMI 命令查询所有传感器。可通过带内与带外的方式查询，命令为 sensor list 。

  • 带内查询： ipmitool sensor list
  • 带外查询： ipmitool -I lanplus -H <host> -p 623 -U <username> -P <password> -C 17 sensor list

• CLI

  openUBMC 支持 CLI 命令查询所有传感器。SSH 登录 openUBMC 后执行命令 ipmcget -t sensor -d list 。

• Redfish

  openUBMC 支持 redfish 接口查询。通过 get 请求分别查询门限传感器和离散传感器。使用Postman工具向测试环境发送下列请求：

  • 门限传感器 uri：redfish/v1/Chassis/:chassisid/ThresholdSensors
  • 离散传感器 uri：redfish/v1/Chassis/:chassisid/DiscreteSensors