📋 文档信息

项目	内容
文档标题	Sensor类配置字典
版本	v1.0
创建日期	2025-01-27
最后更新	2025-01-27
维护状态	✅ 活跃维护

📋 变更历史记录

文档变更记录

版本	发布日期	变更类型	变更内容	影响范围	维护人员
v1.0	2025-01-27	初始版本	创建Sensor类配置字典	全新文档	系统管理员

🎯 类概览

Sensor 类系统

属性	值
类名称	`Sensor` (Entity + ThresholdSensor + DiscreteSensor)
功能描述	传感器管理系统，包含实体管理(Entity)、门限传感器(ThresholdSensor)和离散传感器(DiscreteSensor)，提供完整的传感器配置和监控功能
所属SIG组	sensor
所属组件	sensor
责任人	传感器管理组
最后更新	2025-01-27
状态	🟢 正常运行

📊 属性定义详表

Entity 类 - 必选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`Id`	U8	-	U8	-	传感器对应的实体标识具体参照IPMI标准协议规范Table 43-, Entity ID Codes(P550) 常用的实体标识列举如下： `03h` processor `04h` disk or disk bay `07h` system board `0Ah` power supply `0Bh` add-in card `12h` processor board `1Eh` cooling unit `20h` memory device `37h` air inlet	配置传感器实体	`7`	CSR	软件
`Instance`	U8	-	U8	-	传感器对应的实体实例标识，通常以0x60开始配置，理论上应保证相同Id下Instance不同具体参照 Section 39.1 System- and Device-relatice Entity Instance Values(P492)	配置传感器实体	`96`	CSR	软件
`Name`	String	-	String	-	实体名称	配置传感器实体	`"MainBoard"`	CSR	软件
`Presence`	U8	1	默认1或者关联部件在位	-	实体在位状态，部件不存在动态拔插则配死为1，否则应关联对应的在位信号	配置传感器实体	`1`	CSR	软件
`PowerState`	Mixed	1	默认1或者关联部件在位	Scanner_PowerGood	实体上下电状态，若与上下电状态无关则配死为1，否则应关联上下电信号	配置传感器实体	`"<=/Scanner_PowerGood.Value"`	CSR	软件

Entity 类 - 可选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`Slot`	U8	255	U8	-	实体所在的槽位，默认0xFF	配置传感器实体	`255`	CSR	软件

ThresholdSensor 类 - 必选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`OwnerId`	U8	32	-	-	传感器所有者ID	配置传感器对象	`32`	CSR	软件
`OwnerLun`	U8	0	-	-	传感器所有者LUN	配置传感器对象	`0`	CSR	软件
`EntityId`	Mixed	-	关联Entity的Id	Entity_MainBoard	传感器需要关联实体，关联对应实体的Id属性	配置传感器对象	`"<=/Entity_MainBoard.Id"`	CSR	软件
`EntityInstance`	Mixed	-	关联Entity的Instance	Entity_MainBoard	传感器需要关联实体，关联对应实体的Instance属性	配置传感器对象	`"<=/Entity_MainBoard.Instance"`	CSR	软件
`Initialization`	U8	127	U8	-	传感器初始化选项，门限传感器 - 0x7F	配置传感器对象	`127`	CSR	软件
`Capabilities`	U8	232	U8	-	传感器能力，用于配置包括自动调整模式、迟滞量、阈值访问、事件控制等特性，具体如下 [7] - 1b=当实体不在位或禁用时忽略传感器，与关联的`Entity`的`PowerState`与`Presence`状态有关，若`Entity`的这两个状态默认配置为1，通常配置为 0b [6] - 支持传感器自动重新调整，通常配置为 1b 0b=no(手动) 1b=yes(自动) [5:4] - 支持传感器迟滞量，门限传感器通常配置为 10b 00b=无迟滞量 01b=迟滞量可读 10b=迟滞量可读可写 11b=固定的不可读迟滞量 [3:2] - 支持传感器阈值访问，门限传感器通常配置为 10b 00b=无阈值 01b=基于`ReadingMask`配置支持的阈值可读 10b=基于`ReadingMask`及`Settable Threshold Mask`配置支持的阈值可读可写 11b=固定的不可读的阈值，通过`ReadingMask`反映 [1:0] - 支持事件信息控制，通常配置为 00b 00b=支持控制每个阈值、离散状态的启动及禁用 01b=仅支持整个传感器 10b=仅支持全局禁用 11b=无来自传感器的事件综上，针对连续传感器，建议配置为： ①若传感器使能状态不受实体在位及上下电影响，则配置为`104` ②若传感器使能状态受实体在位及上下电影响，则配置为`232`	配置传感器对象	`232`	CSR	软件
`SensorType`	U8	-	U8	-	传感器类型具体参照 Table 42-, Sensor Type Codes(P505)	配置传感器对象	`1`	CSR	硬件
`ReadingType`	U8	1	U8	-	传感器读值类型，ThresholdSensor则配置为0x01 具体参照 Table 42-, Event/Reading Type Code Ranges(P503)	配置传感器对象	`1`	CSR	硬件
`SensorName`	String	-	String	-	传感器名称	配置传感器对象	`"BCU${Slot} VCC_12V0_1"`	CSR	硬件
`AssertMask`	U16	-	U16	-	传感器事件产生掩码，决定是否能产生事件；配置门限场景使用，具体含义见IPMI标准协议规范43.1章节	配置传感器对象	`516`	CSR	硬件
`DeassertMask`	U16	-	U16	-	传感器事件恢复掩码，决定是否能恢复事件；配置门限场景使用，具体含义见IPMI标准协议规范43.1章节	配置传感器对象	`516`	CSR	硬件
`ReadingMask`	U16	-	U16	-	传感器读值掩码，决定是否能对外显示门限；配置门限场景使用，具体含义见IPMI标准协议规范43.1章节	配置传感器对象	`4626`	CSR	硬件
`Unit`	U8	-	U8	-	传感器单位配置，具体含义见IPMI标准协议规范43.1章节 ①传感器读值为有符号数，如温度：配置为128 ②传感器读值为无符号数，如功率：配置为0	配置传感器对象	`128`	CSR	软件
`BaseUnit`	U8	-	U8	-	传感器基本单位具体参照IPMI标准协议规范Table 43-, Sensor Unit Type Codes(P554) 常用的传感器单位列举如下： `1` degrees C `4` Volts `5` Amps `6` Watts `18` RPM	配置传感器对象	`4`	CSR	硬件
`M`	U8	1	U8	-	按需配置，无原始值缩放转换需求，则默认配置为1	配置传感器对象	`6`	CSR	硬件
`MaximumReading`	U8	-	U8	-	实际最大值，与数据格式有关 ①有符号数，配置为127 ②无符号数，配置为255	配置传感器对象	`255`	CSR	硬件
`MinimumReading`	U8	-	U8	-	实际最小值，与数据格式有关 ①有符号数，配置为128 ②无符号数，配置为0	配置传感器对象	`0`	CSR	软件
`Reading`	Mixed	-	关联数据源	Scanner_12v1、Scanner_PowerGood	传感器原始读值	配置传感器对象	`"<=/Scanner_12v1.Value;<=/Scanner_PowerGood.Value	> expr(($2 == 0) ? 0 : (($1 / 12) > 255 ? 204 : ($1 / 12)))"`	CSR
`ReadingStatus`	Mixed	-	关联数据源	Scanner_12v1、Scanner_PowerGood	传感器读值状态：0：normal	配置传感器对象	`"<=/Scanner_12v1.Status;<=/Scanner_12v1.Value;<=/Scanner_PowerGood.Value	> expr((($1 == 0) && (($2 / 12) > 255) && ($3 == 1)) ? 2 : $1)"`	CSR

ThresholdSensor 类 - 可选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`RBExp`	U8	224	U8	-	按需配置，无原始值缩放转换需求，则可配置	配置传感器对象	`224`	CSR	硬件
`NominalReading`	U8	204	U8	-	名义读值，无实际含义，在数据格式范围内即可	配置传感器对象	`204`	CSR	硬件
`UpperCritical`	U8	220	U8	-	按需配置，传感器严重事件上限	配置传感器对象	`220`	CSR	硬件
`LowerCritical`	U8	180	U8	-	按需配置，传感器严重事件下限	配置传感器对象	`180`	CSR	硬件
`UpperNoncritical`	U8	0	U8	-	按需配置，传感器一般事件上限	配置传感器对象	`0`	CSR	硬件
`LowerNonCritical`	U8	0	U8	-	按需配置，传感器一般事件下限	配置传感器对象	`0`	CSR	硬件
`UpperNonrecoverable`	U8	0	U8	-	按需配置，传感器紧急事件上限	配置传感器对象	`0`	CSR	硬件
`LowerNonrecoverable`	U8	0	U8	-	按需配置，传感器紧急事件下限	配置传感器对象	`0`	CSR	硬件
`PositiveHysteresis`	U8	4	U8	-	按需配置，传感器上升事件恢复迟滞量	配置传感器对象	`4`	CSR	硬件
`NegativeHysteresis`	U8	4	U8	-	按需配置，传感器下降事件恢复迟滞量	配置传感器对象	`4`	CSR	硬件
`SensorNumber`	U8	255	U8	-	无传感器编号定制需求，则不配置或配死为255，由sensor模块分配	配置传感器对象	`255`	CSR	软件

DiscreteSensor 类 - 必选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`EntityId`	Mixed	-	关联Entity的Id	Entity_MainBoard	传感器需要关联实体，关联对应实体的Id属性	配置传感器对象	`"<=/Entity_MainBoard.Id"`	CSR	软件
`EntityInstance`	Mixed	-	关联Entity的Instance	Entity_MainBoard	传感器需要关联实体，关联对应实体的Instance属性	配置传感器对象	`"<=/Entity_MainBoard.Instance"`	CSR	软件
`Initialization`	U8	99	U8	-	传感器初始化选项，离散传感器 - 0x63	配置传感器对象	`99`	CSR	软件
`Capabilities`	U8	64	U8	-	传感器能力，用于配置包括自动调整模式、迟滞量、阈值访问、事件控制等特性，具体如下 [7] - 1b=当实体不在位或禁用时忽略传感器，与关联的`Entity`的`PowerState`与`Presence`状态有关，若`Entity`的这两个状态默认配置为1，通常配置为 0b [6] - 支持传感器自动重新调整，通常配置为 1b 0b=no(手动) 1b=yes(自动) [5:4] - 支持传感器迟滞量，离散传感器通常配置为 00b 00b=无迟滞量 01b=迟滞量可读 10b=迟滞量可读可写 11b=固定的不可读迟滞量 [3:2] - 支持传感器阈值访问，离散传感器通常配置为 00b 00b=无阈值 01b=基于`ReadingMask`配置支持的阈值可读 10b=基于`ReadingMask`及`Settable Threshold Mask`配置支持的阈值可读可写 11b=固定的不可读的阈值，通过`ReadingMask`反映 [1:0] - 支持事件信息控制，通常配置为 00b 00b=支持控制每个阈值、离散状态的启动及禁用 01b=仅支持整个传感器 10b=仅支持全局禁用 11b=无来自传感器的事件综上，针对离散传感器，建议配置为： ①若传感器使能状态不受实体在位及上下电影响，则配置为`64` ②若传感器使能状态受实体在位及上下电影响，则配置为`192`	配置传感器对象	`64`	CSR	软件
`SensorType`	U8	-	U8	-	传感器类型具体参照 Table 42-, Sensor Type Codes(P505)	配置传感器对象	`35`	CSR	硬件
`ReadingType`	U8	-	U8	-	传感器读值类型具体参照 Table 42-, Event/Reading Type Code Ranges(P503)	配置传感器对象	`111`	CSR	硬件
`SensorName`	String	-	String	-	传感器名称	配置传感器对象	`"Watchdog2"`	CSR	硬件
`AssertMask`	U16	-	U16	-	传感器事件产生掩码，决定是否能产生事件；配置事件场景使用，具体含义见IPMI标准协议规范43.2章节	配置传感器对象	`271`	CSR	硬件
`DeassertMask`	U16	-	U16	-	传感器事件恢复掩码，决定是否能恢复事件；配置事件场景使用，具体含义见IPMI标准协议规范43.2章节	配置传感器对象	`271`	CSR	硬件
`DiscreteMask`	U16	-	U16	-	传感器离散值掩码，具体含义见IPMI标准协议规范43.2章节	配置传感器对象	`271`	CSR	硬件
`Unit`	U8	192	U8	-	传感器单位配置，离散传感器-0xc0	配置传感器对象	`192`	CSR	软件
`BaseUnit`	U8	0	U8	-	离散传感器无单位，配置为0	配置传感器对象	`0`	CSR	硬件
`DiscreteType`	U8	0	U8	-	传感器离散类型，具体是什么类型参照 Table 42-, Sensor Type Codes(P505) 普通离散：0 数字离散：1（事件互斥）	配置传感器对象	`0`	CSR	软件

DiscreteSensor 类 - 可选属性

属性名	类型	默认值	取值范围	动态关联	描述	使用场景	举例	来源	分类
`SensorNumber`	U8	255	U8	-	无传感器编号定制需求，则不配置或配死为255，由sensor模块分配	配置传感器对象	`255`	CSR	软件

🔗 动态关联机制

语法规范

使用 <=/xxx 和表达式语法实现动态关联：

yaml

# Entity关联
EntityId: "<=/Entity_MainBoard.Id"
EntityInstance: "<=/Entity_MainBoard.Instance"

# 电源状态关联
PowerState: "<=/Scanner_PowerGood.Value"

# 传感器读值关联和表达式
Reading: "<=/Scanner_12v1.Value;<=/Scanner_PowerGood.Value |> expr(($2 == 0) ? 0 : (($1 / 12) > 255 ? 204 : ($1 / 12)))"

# 传感器状态关联
ReadingStatus: "<=/Scanner_12v1.Status;<=/Scanner_12v1.Value;<=/Scanner_PowerGood.Value |> expr((($1 == 0) && (($2 / 12) > 255) && ($3 == 1)) ? 2 : $1)"

关联说明

Entity关联: 传感器必须关联对应的实体对象
PowerState: 可关联电源状态信号，支持动态上下电控制
Reading: 支持复杂表达式计算，可关联多个Scanner值
ReadingStatus: 传感器状态管理，支持条件表达式

📂 分类标准

硬件属性

定义：与硬件特性和物理参数直接相关的属性
特点：通常与IPMI标准协议规范对应，反映硬件特性
示例：SensorType, ReadingType, SensorName, AssertMask, DeassertMask, ReadingMask, BaseUnit, M, RBExp, NominalReading, UpperCritical, LowerCritical, UpperNoncritical, LowerNonCritical, UpperNonrecoverable, LowerNonrecoverable, PositiveHysteresis, NegativeHysteresis, MaximumReading, Reading, ReadingStatus

软件属性

定义：用于逻辑控制和软件管理的参数
特点：由CSR配置管理，用于传感器逻辑控制
示例：Id, Instance, Slot, Name, Presence, PowerState, OwnerId, OwnerLun, EntityId, EntityInstance, Initialization, Capabilities, Unit, MinimumReading, SensorNumber, DiscreteType

📝 配置示例

温度传感器配置

json

{
  "Entity": {
    "Id": 7,
    "Instance": 96,
    "Name": "MainBoard",
    "Presence": 1,
    "PowerState": "<=/Scanner_PowerGood.Value",
    "Slot": 255
  },
  "ThresholdSensor": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_MainBoard.Id",
    "EntityInstance": "<=/Entity_MainBoard.Instance",
    "Initialization": 127,
    "Capabilities": 232,
    "SensorType": 1,
    "ReadingType": 1,
    "SensorName": "CPU Temperature",
    "AssertMask": 516,
    "DeassertMask": 516,
    "ReadingMask": 4626,
    "Unit": 128,
    "BaseUnit": 1,
    "M": 1,
    "MaximumReading": 127,
    "MinimumReading": 128,
    "UpperCritical": 85,
    "LowerCritical": 0,
    "PositiveHysteresis": 2,
    "NegativeHysteresis": 2,
    "Reading": "<=/Scanner_CpuTemp.Value",
    "ReadingStatus": "<=/Scanner_CpuTemp.Status",
    "SensorNumber": 255
  }
}

电压传感器配置

json

{
  "Entity": {
    "Id": 7,
    "Instance": 97,
    "Name": "PowerBoard",
    "Presence": 1,
    "PowerState": "<=/Scanner_PowerGood.Value",
    "Slot": 255
  },
  "ThresholdSensor": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_PowerBoard.Id",
    "EntityInstance": "<=/Entity_PowerBoard.Instance",
    "Initialization": 127,
    "Capabilities": 232,
    "SensorType": 2,
    "ReadingType": 1,
    "SensorName": "BCU1 VCC_12V0_1",
    "AssertMask": 516,
    "DeassertMask": 516,
    "ReadingMask": 4626,
    "Unit": 0,
    "BaseUnit": 4,
    "M": 6,
    "RBExp": 224,
    "NominalReading": 204,
    "MaximumReading": 255,
    "MinimumReading": 0,
    "UpperCritical": 220,
    "LowerCritical": 180,
    "PositiveHysteresis": 4,
    "NegativeHysteresis": 4,
    "Reading": "<=/Scanner_12v1.Value;<=/Scanner_PowerGood.Value |> expr(($2 == 0) ? 0 : (($1 / 12) > 255 ? 204 : ($1 / 12)))",
    "ReadingStatus": "<=/Scanner_12v1.Status;<=/Scanner_12v1.Value;<=/Scanner_PowerGood.Value |> expr((($1 == 0) && (($2 / 12) > 255) && ($3 == 1)) ? 2 : $1)",
    "SensorNumber": 255
  }
}

离散传感器配置

json

{
  "Entity": {
    "Id": 7,
    "Instance": 98,
    "Name": "SystemBoard",
    "Presence": 1,
    "PowerState": 1,
    "Slot": 255
  },
  "DiscreteSensor": {
    "EntityId": "<=/Entity_SystemBoard.Id",
    "EntityInstance": "<=/Entity_SystemBoard.Instance",
    "Initialization": 99,
    "Capabilities": 64,
    "SensorType": 35,
    "ReadingType": 111,
    "SensorName": "Watchdog2",
    "AssertMask": 271,
    "DeassertMask": 271,
    "DiscreteMask": 271,
    "Unit": 192,
    "BaseUnit": 0,
    "DiscreteType": 0,
    "SensorNumber": 255
  }
}

风扇传感器配置

json

{
  "Entity": {
    "Id": 29,
    "Instance": 96,
    "Name": "FanBoard",
    "Presence": 1,
    "PowerState": "<=/Scanner_PowerGood.Value",
    "Slot": 255
  },
  "ThresholdSensor": {
    "OwnerId": 32,
    "OwnerLun": 0,
    "EntityId": "<=/Entity_FanBoard.Id",
    "EntityInstance": "<=/Entity_FanBoard.Instance",
    "Initialization": 127,
    "Capabilities": 232,
    "SensorType": 4,
    "ReadingType": 1,
    "SensorName": "Fan1 Speed",
    "AssertMask": 516,
    "DeassertMask": 516,
    "ReadingMask": 4626,
    "Unit": 0,
    "BaseUnit": 18,
    "M": 1,
    "MaximumReading": 255,
    "MinimumReading": 0,
    "LowerCritical": 20,
    "PositiveHysteresis": 2,
    "NegativeHysteresis": 2,
    "Reading": "<=/Scanner_FanSpeed.Value",
    "ReadingStatus": "<=/Scanner_FanSpeed.Status",
    "SensorNumber": 255
  }
}

🔧 使用指南

配置步骤

创建实体对象：首先配置Entity，定义传感器所属的实体
选择传感器类型：根据需要选择ThresholdSensor或DiscreteSensor
关联实体：通过EntityId和EntityInstance关联对应的Entity
配置传感器属性：设置SensorType、ReadingType、SensorName等基本属性
设置掩码：配置AssertMask、DeassertMask、ReadingMask等掩码
配置单位和范围：设置Unit、BaseUnit、MaximumReading、MinimumReading等
关联数据源：通过Reading和ReadingStatus关联Scanner等数据源
设置门限：配置UpperCritical、LowerCritical等门限值（ThresholdSensor）
配置迟滞量：设置PositiveHysteresis、NegativeHysteresis避免抖动

注意事项

IPMI标准遵循：所有配置必须符合IPMI标准协议规范
实体关联：传感器必须关联对应的Entity对象
数据格式：注意有符号数和无符号数的MaximumReading和MinimumReading配置
Capabilities配置：根据实体的在位和上下电状态选择合适的Capabilities值
传感器编号：SensorNumber建议配置为255，由sensor模块自动分配
表达式语法：使用复杂表达式时需要确保语法正确
门限设置：ThresholdSensor的门限值要在MinimumReading和MaximumReading范围内

性能建议

合理设置迟滞量：避免传感器事件频繁触发和恢复
优化Reading表达式：复杂表达式可能影响性能
实体状态管理：合理配置Presence和PowerState减少无效扫描
传感器分组：相同类型的传感器可以考虑优化配置策略

故障排查

传感器不显示：检查Entity关联和Capabilities配置
读值异常：检查Reading表达式和数据源关联
事件不触发：检查AssertMask和DeassertMask配置
门限显示错误：检查ReadingMask和门限值配置
单位显示错误：检查Unit和BaseUnit配置
传感器状态异常：检查ReadingStatus表达式和实体状态

📋 文档信息 ​

📋 变更历史记录 ​

文档变更记录 ​

🎯 类概览 ​

Sensor 类系统 ​

📊 属性定义详表 ​

Entity 类 - 必选属性 ​

Entity 类 - 可选属性 ​

ThresholdSensor 类 - 必选属性 ​

ThresholdSensor 类 - 可选属性 ​

DiscreteSensor 类 - 必选属性 ​

DiscreteSensor 类 - 可选属性 ​

🔗 动态关联机制 ​

语法规范 ​

关联说明 ​

📂 分类标准 ​

硬件属性 ​

软件属性 ​

📝 配置示例 ​

温度传感器配置 ​

电压传感器配置 ​

离散传感器配置 ​

风扇传感器配置 ​

🔧 使用指南 ​

配置步骤 ​

注意事项 ​

性能建议 ​

故障排查 ​

📋 文档信息

📋 变更历史记录

文档变更记录

🎯 类概览

Sensor 类系统

📊 属性定义详表

Entity 类 - 必选属性

Entity 类 - 可选属性

ThresholdSensor 类 - 必选属性

ThresholdSensor 类 - 可选属性

DiscreteSensor 类 - 必选属性

DiscreteSensor 类 - 可选属性

🔗 动态关联机制

语法规范

关联说明

📂 分类标准

硬件属性

软件属性

📝 配置示例

温度传感器配置

电压传感器配置

离散传感器配置

风扇传感器配置

🔧 使用指南

配置步骤

注意事项

性能建议

故障排查