SPB Git

Repository Public License

thermal.md 8.9 KB

# Thermal metrics

Sources: Collectors/PowerThermalGPU.swift (ThermalLevel, PowerMath.batteryFields, SensorCapabilityResolver), Metrics/Metric.swift, App/Sources/Features/SystemViews.swift (ThermalView), App/Sources/Features/DashboardView.swift (ThermalText, ThermalScale).

# Position

ORIX Monitor reports the thermal state — the operating system's own assessment — and nothing it would have to obtain from the System Management Controller. It shows no CPU temperature, no GPU temperature and no fan speed. Those rows appear on the Thermal & Sensors page marked "Unavailable" with the sentence "Not available through supported system interfaces."

# Stored metrics

Key (MetricID) Name Unit Quality Source API Stored value Refresh
thermal.state (thermalState) Thermal state level measured ProcessInfo.thermalState 0 = nominal, 1 = fair, 2 = serious, 3 = critical every tick of the fast tier (2 s by default while a window is visible)
battery.temperature (batteryTemperature) Battery temperature °C bestEffort IORegistry AppleSmartBattery (Temperature) value / 100 slow tier (30 s by default); only when the key exists

thermal.state is the only metric that is always present in a tick's values: it needs no baseline and no hardware.

# Thermal state

ThermalLevel.current() wraps ProcessInfo.processInfo.thermalState:

Level Raw value Text shown (ThermalText.explanation) Colour role
Nominal 0 The system is within its normal thermal range. success
Fair 1 The system is slightly warm. Performance is not affected. primary text
Serious 2 The system is hot. macOS may reduce performance. warning
Critical 3 The system is very hot. macOS is reducing performance to cool down. danger

An unknown future case of the system enum maps to nominal.

Properties of this signal:

  • It is ordinal, not a temperature. There is no conversion to degrees and ORIX Monitor attempts none.
  • It is the state macOS itself uses to decide about throttling, which makes it the relevant signal for "is heat affecting performance".
  • It is stored as a number so it can be charted, aggregated per bucket (min / avg / max) and used in rules. Bucket averages can be fractional (for example 1.4 when the minute was partly fair and partly serious), so thresholds are placed halfway between levels:
    • default alert: thermal.state above 1.5 for 30 s → critical alert ("at or above Serious");
    • thermalPressure finding: bucket average above 1.5 for at least 60 s; critical if the peak reached 3. See alerts.
  • A change of thermal state (ProcessInfo.thermalStateDidChangeNotification) also forces the slow-tier readings to refresh on the next tick.

There is no percentage convention for either thermal metric.

# Display

Place Content
Thermal & Sensors page, "Thermal state" Level name (large), caption "The system's own assessment", a four-step scale (ThermalScale), the explanation sentence
"Thermal state over time" Live chart with the y axis labelled by level names (ticks at 0, 1, 2, 3)
Dashboard "Thermal state" widget Level and scale
Menu bar panel header Level name
History, Incident and System Overview reports Stored series; the preview and PDF print level names

The level name is always written out; the scale and the colour are secondary cues.

# Battery temperature

The one temperature ORIX Monitor may display, and only as a best-effort value.

  • Source: the Temperature property of the AppleSmartBattery registry entry (or BatteryData.Temperature), read with IORegistryEntryCreateCFProperties. The property name is not documented by Apple.
  • Conversion: hundredths of a degree Celsius → value / 100.
  • Validation: PowerMath.batteryFields discards the value unless it lies within −40…150 °C and is non-zero. An implausible reading yields nil, not a number (flatBatteryLayoutAndImplausibleTemperature checks that 99999 is rejected).
  • Gate: read only when "Read undocumented system properties" is on and the Mac has a battery.
  • Formatting: ValueFormatter.temperature formats through Measurement<UnitTemperature> with the user's locale, one decimal.

On the audited Mac (MacBook Pro Mac17,6, macOS 27.0) the key is not published. The page then shows an unavailable row: "The battery gauge on this Mac and macOS version publishes no temperature." No battery.temperature series exists on that machine. The code path that displays the value is exercised by unit tests on a synthetic registry dictionary, not by a live reading.

A battery temperature is not a proxy for CPU temperature and is not presented as one.

# The capability table

The Thermal & Sensors page also hosts "Sensor and metric availability on this Mac": the thirty rows of SensorCapabilityResolver.resolve() with a filter field. Columns: metric (with an explanatory note), area, access class (Public API / Needs your permission / System command / Needs a privileged helper / Not exposed / Estimate / Best effort), whether it could be read on this Mac just now, and the source. It is evaluated once at launch. The classification of every row is documented in the capability matrix.

Thermal-category rows:

id Name Class Present
thermal.state Thermal state Public API always
cpu.temperature CPU temperature Not exposed never
gpu.temperature GPU temperature Not exposed never
thermal.fans Fan speed Not exposed never
battery.temperature Battery temperature Best effort when the registry key exists

The live test capabilityMatrixIsHonest asserts that no row classified unavailable is ever marked present, and that fans and CPU temperature are classified unavailable.

# Why no SMC readings

Stated on the page itself:

Chip temperatures and fan speeds exist only behind the System Management Controller and private sensor services. ORIX Monitor does not use them: they are undocumented, differ between Mac models, and can break with any update. The thermal state above is the supported signal.

In more detail:

  1. No documentation. SMC keys are four-character codes whose meaning Apple does not publish. Mappings in circulation come from reverse engineering.
  2. Model-specific. The set of keys and what each one measures changes between Mac models and chip generations. A table that is right on one Mac can be silently wrong on another.
  3. Wrong keys fail silently. A mis-identified sensor returns a plausible number. ORIX Monitor's rule is that a displayed number must be traceable to a supported interface or be labelled otherwise; an unlabelled plausible-but-wrong temperature is the exact outcome that rule exists to prevent.
  4. No stability guarantee. A system update can change or remove the interface.
  5. A supported alternative exists for the question users actually have ("is my Mac throttling because of heat?"): the thermal state.

A UI test (testUnavailableSensorsAreDeclaredNotInvented) opens this page and fails if the unavailable sentence is missing or if any text matching an "rpm" value is displayed.

# Quality classes

  • measured — thermal state.
  • bestEffort — battery temperature.
  • unavailable — CPU temperature, GPU temperature, fan speed (displayed as such; not metrics).

# Limitations

  • Four levels only. The thermal state cannot distinguish "comfortably cool" from "about to become fair"; it gives no early warning in degrees.
  • Sampled. A brief change of state between two samples is missed by the series, although the change notification still triggers a slow-tier refresh.
  • No cause attribution. The state says the system is hot, not which component or process is responsible. The Insights text suggests checking vents and placement and states that one event does not indicate a hardware fault.
  • Battery temperature availability depends on model and macOS version, and was absent on the only Mac audited.
  • No fan information of any kind, including whether the Mac has fans.

# Deliberately not shown

Item Reason
CPU temperature (die, cores, clusters) SMC / private HID sensor services only.
GPU temperature Same.
SSD / NAND temperature NVMe SMART or SMC only. See disk.
Fan speed (RPM), fan count SMC only.
Fan control Would require writing to the SMC; out of the question for an app that installs no helper.
Ambient, palm-rest, airflow and other sensors SMC only.
A temperature estimated from load or thermal state It would be an invented number.
A "thermal pressure percentage" The system publishes a level; no percentage exists to report.
Files main
Menu

Theme