Sensor Collector Module

The SensorCollector module is responsible for collecting telemetry data from various hardware sensors on the platform, storing the sensor values, and exposing them via the Redfish API.

When enabled, this module manages the following Redfish resources:

/redfish/v1/Chassis/<ChassisId>/Sensors and individual sensors under it
(Optional, via submodules) Thermal control systems, Power supplies, and Managers

Central Configuration (central_config.proto)

The sensor collector module is configured globally in central_config.proto under the SensorCollectorModule message:

Field Name	Type	Default Value	Description
`enabled`	`bool`	`false`	Enables the sensor collector module.
`allow_sensor_creation_failure`	`bool`	`false`	If true, sensor creation failures will not prevent tlBMC startup (useful for debugging).
`thermal_control_sub_module`	`ThermalControlSubmodule`	N/A	Configuration for the thermal control submodule (Borg, Fan mode, etc.).
`enable_threshold_monitoring`	`bool`	`false`	Periodically monitors sensor thresholds and publishes SEL events when crossed.
`sensor_collection_append_sub_module`	`SensorCollectionAppendSubmodule`	N/A	Appends tlBMC sensors to the collection owned by gBMCWeb.
`own_sensor_collection_in_redfish`	`bool`	`false`	If true, tlBMC will own the sensor collection in Redfish.
`drop_failed_duplicate_sensors`	`bool`	`false`	If true, a sensor that failed creation is dropped at startup when a successfully created sensor with the same key exists.

Thermal Control Submodule

Field Name	Type	Default Value	Description
`enabled`	`bool`	`false`	Enables tlBMC to
: : : : own :
: : : : ThermalSubsystem, :
: : : : Fans, :
: : : : PowerSubsystem, :
: : : : and Managers. :

Sensor Collection Append Submodule

Field Name	Type	Default Value	Description
`enabled`	`bool`	`false`	Appends tlBMC sensors to
: : : : the collection owned by :
: : : : gBMCWeb. :
`per_sensor_append_mode`	`bool`	`false`	Appends individual
: : : : sensors based on Entity :
: : : : Manager configuration :
: : : : rather than the entire :
: : : : collection. :

Entity Manager Configuration

tlBMC relies on Entity Manager (EM) configuration JSON files to discover and initialize sensors. To make tlBMC monitor a sensor, the configuration block must contain "TlbmcOwned": true.

Common EM JSON Keys

All sensors support these common parameters within their JSON exposing block:

Parameter Name	Type / Values	Description
`Name`	`string`	The user-visible name of the
: : : sensor. :
`Type`	`string`	The hardware driver/sensor
: : : type. See supported types :
: : : below. :
`Bus`	`integer` or `string`	The I2C logical bus (e.g. `2`,
: : : or dynamic expressions like :
: : : `"$bus"`). :
`Address`	`string`	The I2C device address in hex
: : : format (e.g. `"0x4c"`). :
`TlbmcOwned`	`boolean`	Must be `true` for tlBMC to
: : : instantiate this sensor :
: : : config. :
`PowerState`	`string`	Dependency on host power state
: : : (e.g. `"Always"`, `"On"`, :
: : : `"BiosPost"`). :
`HostId`	`string`	Required when `PowerState` is
: : : `"On"` or `"BiosPost"` (e.g. :
: : : `"Host1"`, or expressions like :
: : : `"Host$BUS / 29 + 1"`). :
`RefreshIntervalMs`	`integer`	Polling frequency for the
: : : sensor in milliseconds. :
`Thresholds`	`array`	A list of warning or critical
: : : threshold objects. :
`MinReading` /	`number`	Overrides for default sensor
: `MaxReading` : : reading limits. :

Supported Sensor Types & Chip Drivers

The following hardware chip drivers and sensor types are supported out-of-the-box:

HwmonTemp Sensors (Temperature)

MAX31725
TMP75
MAX31732
SA56004
TMP461
TMP431
TMP421

PSU Sensors (Power / Voltage / Current)

ADM1266
ADM1272
ADM1273
PMBus
LTC2991
RAA228228
TDA38725
TDA38740
XDPE1A2G5B
LTC4287
Q50SN12072
Q54SN120A4
TPS25990
RAA229639
LX6301
SBTSI_I3C
TPS546E25
BMR490
GOOGLE_TPU
XDPE19284C
MAX20826
MAX20830C
MAX20840C
RAA229141
MAX34451
SBRMI_I3C
MP2925
MP2929
MP5998
INA226
RAA229621

ADC Sensors (Voltage)

ADS1015
MAX11611
TLA2024

Fan Tachometer & PWM Sensors

I2CFan (Both Tachometer and PWM controllers)

CPU Sensors

XeonCPU (Intel CPU telemetry over PECI/I2C)

GPIO & Virtual Sensors

GpioSensor
VirtualSensor (Math expression combination of other sensors)

Protobuf Configuration

Below is the list of underlying protobuf schemas representing the parsed configs:

hwmon_temp_sensor_config.proto: Defines config parameters for temperature monitoring.
psu_sensor_config.proto: Defines power supply sensors configuration.
adc_sensor_config.proto: Defines channel mapping and scaling for analog-to-digital converters.
fan_pwm_config.proto: Defines fan pulse-width modulation config.
fan_tach_config.proto: Defines fan tachometer RPM config.
intel_cpu_sensor_config.proto: Defines CPU thermal registers and DTS offsets.
gpio_sensor_config.proto: Defines input GPIO level sensors.
virtual_sensor_config.proto: Defines sensors calculated via mathematical expressions.
sensor_instance_properties.proto: Common physical properties for a sensor instance.
entity_common_config.proto: Base entity configs like refresh intervals and power state requirements.
hal_common_config.proto: Generic I2C logical bus and address representation.
threshold_config.proto: Custom sensor limit warning/critical thresholds.

Protobuf Field Details

HalCommonConfig

Field Name	Type	Description
`bus`	`uint64`	The I2C logical bus number.
`address`	`uint64`	The I2C device target address.

EntityCommonConfig

Field Name	Type	Description
`board_config_key`	`string`	The config key of the parent board.
`refresh_interval`	`google.protobuf.Duration`	The polling rate interval.
`queue_size`	`uint64`	The numeric buffer queue size (default 10).
`config_detected`	`bool`	Tracks whether the sensor was matched during scans.
`sensor_group`	`string`	The parent bus/group string.
`config_name`	`string`	The raw configuration item name.
`power_state`	`SensorPowerRequirement`	Dependency on the host run state (e.g. `SENSOR_POWER_REQUIREMENT_ALWAYS`, `SENSOR_POWER_REQUIREMENT_CHASSIS_ON`, `SENSOR_POWER_REQUIREMENT_BIOS_POST`).

SensorInstanceProperties

Field Name	Type	Description
`name`	`string`	The instance name (unique per sensor).
`unit`	`SensorUnit`	Measurement units (e.g. `UNIT_DEGREE_CELSIUS`, `UNIT_VOLT`, `UNIT_REVOLUTION_PER_MINUTE`).
`thresholds`	`ThresholdConfigs`	Limits triggering warning or critical status.
`reading_ranges`	`ReadingRangeConfigs`	Normal operational bounds (Min/Max values).
`redfish_hidden`	`bool`	Excludes this specific instance from the Redfish tree.
`append_to_sensor_collection`	`bool`	Instructs gBMCWeb to append this sensor explicitly.

Usage & Examples

1. Enabling Sensor Collector in Central Config

general_config {
  sensor_collector_module {
    enabled: true
    enable_threshold_monitoring: true
  }
}

2. Entity Manager Examples

HwmonTemp Sensor Example (TMP431)

{
  "Address": "0x4C",
  "Bus": "$BUS / 29 * 100 + 101",
  "Name": "HPM$BUS / 29 D0_AMBIENT_00_T",
  "Name1": "HPM$BUS / 29 D0_THERMAL_00_T",
  "PowerState": "On",
  "HostId": "Host$BUS / 29 + 1",
  "Thresholds": [
    {
      "Direction": "greater than",
      "Hysteresis": 1.5,
      "Index": 2,
      "Name": "upper critical",
      "Severity": 1,
      "Value": 95
    },
    {
      "Direction": "less than",
      "Hysteresis": 1.5,
      "Index": 2,
      "Name": "lower critical",
      "Severity": 1,
      "Value": 0
    }
  ],
  "TlbmcOwned": true,
  "Type": "TMP431"
}

PSU Sensor Example (ADM1266)

{
  "Address": "0x40",
  "Bus": "$BUS / 29 * 100 + 131",
  "Labels": [
    "vout1",
    "vout2"
  ],
  "Name": "HPM$BUS / 29 ADM1266_U213",
  "PowerState": "On",
  "HostId": "Host$BUS / 29 + 1",
  "Thresholds": [
    {
      "Direction": "greater than",
      "Label": "vout1",
      "Name": "upper critical",
      "Severity": 1,
      "Value": 13.56
    },
    {
      "Direction": "less than",
      "Label": "vout2",
      "Name": "lower critical",
      "Severity": 1,
      "Value": 2.805
    }
  ],
  "TlbmcOwned": true,
  "Type": "ADM1266",
  "vout1_Max": 13.56,
  "vout1_Name": "HPM$BUS / 29 U213_P12V_V",
  "vout2_Min": 0.4,
  "vout2_Name": "HPM$BUS / 29 U213_P3V3_STBY_V"
}

ADC Sensor Example (ADS1015)

{
  "Name": "Thidwick vmon",
  "Bus": "$bus",
  "Address": "0x48",
  "Type": "ADS1015",
  "Labels": [
     "in_voltage0_raw",
     "in_voltage1_raw"
  ],
  "TlbmcOwned": true,
  "AppendToSensorCollection": true,
  "Channels": [
    {
        "SensorName": "PE$bus - 4 MS1_Analog_PG_vout",
        "FileName": "in_voltage0_raw",
        "Units": "Volts",
        "Scale": 1000
    },
    {
        "SensorName": "PE$bus - 4 MS0_Analog_PG_vout",
        "FileName": "in_voltage1_raw",
        "Units": "Volts",
        "Scale": 1000
    }
 ],
 "IntervalMs": 1000
}

CPU Sensor Example (XeonCPU)

{
  "Name": "cpu_sensor",
  "Type": "XeonCPU",
  "Bus": 1,
  "Address": "0x30",
  "CpuID": 0,
  "SensorGroup": "group1",
  "Labels": ["Die", "DIMM A1"],
  "Die_Name": "die",
  "DtsCritOffset": 1000,
  "DIMM_A1_Name": "DIMM1",
  "RelatedItem": [
    {
      "SensorName": "DIMM1",
      "Type": "RESOURCE_TYPE_DIMM",
      "ResourceId": "dimm1"
    }
  ],
  "TlbmcOwned": true
}

GPIO Sensor Example

{
  "Name": "gpio_sensor",
  "Type": "GpioSensor",
  "GpioPinName": "gpio_pin",
  "TlbmcOwned": true,
  "Units": "Volts",
  "RefreshIntervalMs": 1000
}

Virtual Sensor Example

{
  "Name": "virtual_sensor",
  "Type": "VirtualSensor",
  "Expression": "voltage_BMC_P3V3_STBY + voltage_BMC_P1V8",
  "Units": "Volts",
  "RedfishHidden": [ "virtual_sensor" ],
  "TlbmcOwned": true
}

Key Classes & Architecture

SensorCollector: The orchestrator class implementing the module's thread loop. It retrieves physical readings via the platform HAL, updates the sensor store, handles limits, and coordinates Redfish route registries.

Code References

sensor_collector.h
entity_config_json_impl.cc